openapi: 3.0.2
info:
  version: ''
  title: 'DC Project'
  description: 'A free community program for create constitution'

paths:
  /articles:
    get:
      summary: Get all articles
      tags:
        - article
      operationId: getArticles
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/articleSort'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/createdBy'
        - name: workgroup
          in: query
          description: ID of workgroup
          example: 82a0e60a-bb55-dbc0-1c3d-0a804df2b5df
          required: false
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: The Article objects
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Paginated'
                  - type: object
                    properties:
                      result:
                        type: array
                        maxItems: 50
                        items:
                          properties:
                            id:
                              type: string
                              format: uuid
                            title:
                              type: string
                            createdBy:
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                name:
                                  type: object
                                  properties:
                                    firstName:
                                      type: string
                                    lastName:
                                      type: string
                                email:
                                  type: string
                            workgroup:
                              type: object
                              nullable: true
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                name:
                                  type: string
                            draft:
                              type: boolean
    post:
      security:
        - JWTAuth: []
      summary: Create new Article
      tags:
        - article
      operationId: insertArticle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - title
                - content
                - description
                - tags
              properties:
                title:
                  type: string
                  example:
                    Limit power of press
                content:
                  type: string
                  example:
                    Lorem upsum...
                description:
                  type: string
                  example:
                    I think is the bether choice
                tags:
                  type: array
                  items:
                    type: string
                  default: [ ]
                  example: [ power, press ]
                anonymous:
                  type: boolean
                  default: true
                draft:
                  type: boolean
                  default: false
                workgroup:
                  allOf:
                    - $ref: '#/components/schemas/UuidEntity'
                    - default: null
      responses:
        200:
          description: Article created
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: uuid
                  versionId:
                    type: string
                    format: uuid
                  versionNumber:
                    type: integer
        401:
          $ref: '#/components/responses/401'
  /articles/{article}:
    parameters:
      - $ref: '#/components/parameters/article'
    get:
      security:
        - JWTAuth: []
      summary: Get one article
      tags:
        - article
      operationId: getArticle
      responses:
        200:
          description: The Article objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
  /articles/{article}/versions:
    parameters:
      - $ref: '#/components/parameters/article'
    get:
      summary: Get all versions of articles
      tags:
        - article
      operationId: getArticleVersions
      responses:
        200:
          description: The versions of Article
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Paginated'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          additionalProperties: false
                          properties:
                            id:
                              type: string
                              format: uuid
                            title:
                              type: string
                            draft:
                              type: boolean
                            lastVersion:
                              type: boolean
                            createdBy:
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                name:
                                  type: object
                                  properties:
                                    firstName:
                                      type: string
                                    lastName:
                                      type: string
                                email:
                                  type: string
                            workgroup:
                              type: object
                              nullable: true
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                name:
                                  type: string

  /login:
    post:
      summary: sign in
      tags:
        - authentification
      operationId: login
      requestBody:
        description: Login
        required: true
        content:
          application/json:
            schema:
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: username
                  example:
                    john-doe
                password:
                  type: string
                  description: Pasword
                  example:
                    azerty
      responses:
        200:
          description: return JWT
          content:
            text/plain:
              schema:
                type: string
                format: byte
                example:
                  'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJBdXRoZW50aWNhdGlvbiIsImlzcyI6ImRjLXByb2plY3QuZnIiLCJpZCI6ImQ1NDRhNmE4LWJhYjgtNDU2MC05NWIxLThhZjAyMDNkOTEwNCIsImV4cCI6MTU2NzA3Mzc0Mn0.0VTetv8fZFjVgpJ-bwJpidGNHJUOmgj8vuZcZXzwnLa7TtFwcXWvh3bDPYHqB66nmOfXyM57XnHDbmRwtipCag'
            application/json:
              schema:
                properties:
                  token:
                    type: string
                    example:
                      'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJBdXRoZW50aWNhdGlvbiIsImlzcyI6ImRjLXByb2plY3QuZnIiLCJpZCI6ImQ1NDRhNmE4LWJhYjgtNDU2MC05NWIxLThhZjAyMDNkOTEwNCIsImV4cCI6MTU2NzA3Mzc0Mn0.0VTetv8fZFjVgpJ-bwJpidGNHJUOmgj8vuZcZXzwnLa7TtFwcXWvh3bDPYHqB66nmOfXyM57XnHDbmRwtipCag'
  /register:
    post:
      summary: Create account
      tags:
        - authentification
      operationId: register
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - birthday
                - email
                - user
              properties:
                name:
                  type: object
                  required:
                    - firstName
                    - lastName
                  properties:
                    firstName:
                      type: string
                      example:
                        john
                    lastName:
                      type: string
                      example:
                        Doe
                birthday:
                  type: string
                  format: 'date'
                  example: '1984-12-25'
                email:
                  type: string
                  format: email
                  example: my.email@dc-project.fr
                user:
                  type: object
                  required:
                    - username
                    - password
                  properties:
                    username:
                      type: string
                      example:
                        john-doe
                    password:
                      type: string
                      example:
                        azerty
                      format: password
      responses:
        200:
          description: User created and JWT returned
          content:
            text/plain:
              example:
                'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJBdXRoZW50aWNhdGlvbiIsImlzcyI6ImRjLXByb2plY3QuZnIiLCJpZCI6ImQ1NDRhNmE4LWJhYjgtNDU2MC05NWIxLThhZjAyMDNkOTEwNCIsImV4cCI6MTU2NzA3Mzc0Mn0.0VTetv8fZFjVgpJ-bwJpidGNHJUOmgj8vuZcZXzwnLa7TtFwcXWvh3bDPYHqB66nmOfXyM57XnHDbmRwtipCag'
            application/json:
              schema:
                properties:
                  token:
                    type: string
                    example:
                      'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJBdXRoZW50aWNhdGlvbiIsImlzcyI6ImRjLXByb2plY3QuZnIiLCJpZCI6ImQ1NDRhNmE4LWJhYjgtNDU2MC05NWIxLThhZjAyMDNkOTEwNCIsImV4cCI6MTU2NzA3Mzc0Mn0.0VTetv8fZFjVgpJ-bwJpidGNHJUOmgj8vuZcZXzwnLa7TtFwcXWvh3bDPYHqB66nmOfXyM57XnHDbmRwtipCag'
        400:
          description: Bad request
          content:
            application/json:
              schema:
                description: sdf
  /auth/passwordless:
    post:
      summary: Send a connexion link by email
      description: Send a connexion link by email with the token required to the connexion
      externalDocs:
        description: Explanation of Passwordless auth
        url: https://en.wikipedia.org/wiki/Passwordless_authentication
      tags:
        - authentification
      operationId: passwordless
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  type: string
                  format: email
                  description: email to send the token
                  example:
                    my.email@dc-project.fr
                url:
                  type: string
                  description: url tu redirect with the token
                  example:
                    http://dc-project.fr/auth/passwordless
      responses:
        204:
          description: email send
        404:
          description: no user with this email

  /citizens:
    get:
      security:
        - JWTAuth: []
      summary: Get all citizens
      tags:
        - citizen
      operationId: getCitizens
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/search'
      responses:
        200:
          description: The Citizen objects
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Paginated'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/CitizenListResponse'
        401:
          $ref: '#/components/responses/401'
  /citizens/current:
    get:
      security:
        - JWTAuth: []
      summary: Get Citizen
      tags:
        - citizen
      operationId: getCurrentCitizen
      responses:
        200:
          description: The Citizen object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitizenResponse'
  /citizens/{citizen}:
    parameters:
      - $ref: '#/components/parameters/citizen'
    get:
      security:
        - JWTAuth: []
      summary: Get Citizen
      tags:
        - citizen
      operationId: getCitizen
      responses:
        200:
          description: The Citizen object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitizenResponse'
        404:
          description: Citizen not found
        401:
          $ref: '#/components/responses/401'
  /citizens/{citizen}/password/change:
    parameters:
      - $ref: '#/components/parameters/citizen'
    put:
      security:
        - JWTAuth: [ ]
      summary: Change Citizen Password
      tags:
        - citizen
      operationId: changePassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - oldPassword
                - newPassword
              properties:
                oldPassword:
                  type: string
                  format: password
                  example:
                    azerty
                newPassword:
                  type: string
                  format: password
                  example:
                    qwerty
      responses:
        201:
          description: Password changed
        400:
          description: Bad request
        401:
          $ref: '#/components/responses/401'
        404:
          description: Citizen not found

  /articles/{article}/comments:
    parameters:
      - $ref: '#/components/parameters/article'
    get:
      summary: Get comments of one article
      tags:
        - comment
        - article
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search'
        - name: sort
          in: query
          required: false
          example:
            - created_at
            - votes
          schema:
            type: string
            default: created_at
            enum:
              - created_at
              - votes
      responses:
        200:
          description: Return paginated comments of article
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Paginated'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/CommentResponse'
    post:
      security:
        - JWTAuth: [ ]
      summary: Create Comment to article
      tags:
        - comment
        - article
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  example:
                    Lorem ipsum...
      responses:
        201:
          description: Return created Comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        401:
          $ref: '#/components/responses/401'
  /comments/{comment}:
    parameters:
      - $ref: '#/components/parameters/comment'
    get:
      summary: Get Comment by Comment ID
      tags:
        - comment
      responses:
        200:
          description: Return Comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
    put:
      security:
        - JWTAuth: []
      summary: Edit existing comment
      tags:
        - comment
      requestBody:
        content:
          application/json:
            schema:
              required:
                - content
              properties:
                content:
                  type: string
                  example:
                    Lorem ipsum...
      responses:
        200:
          description: Return updated comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        401:
          $ref: '#/components/responses/401'

components:
  parameters:
    page:
      name: page
      in: query
      description: The current page
      example: 1
      required: false
      schema:
        default: 1
        type: integer
        minimum: 1
    limit:
      name: limit
      in: query
      description: The number of object per page
      example: 50
      required: false
      schema:
        default: 50
        type: integer
        minimum: 1
        maximum: 50
    sort:
      name: sort
      in: query
      description: The sort field name
      example: firstName
      required: false
      schema:
        type: string
    articleSort:
      name: sort
      in: query
      description: The sort field name
      example: createdAt
      required: false
      schema:
        type: string
        enum:
          - title
          - createdAt
          - vote
          - popularity
    direction:
      name: direction
      in: query
      description: The sort direction
      example: asc
      required: false
      schema:
        type: string
        default: asc
        enum: [asc, desc]
    search:
      name: search
      in: query
      description: A text to seach
      example: content50
      required: false
      schema:
        type: string
    createdBy:
      name: createdBy
      in: query
      description: filter by Author
      example: 4d673bfa-eaef-4290-b52f-85a9c8a7eba5
      required: false
      schema:
        type: string
        format: uuid

    article:
      name: article
      in: path
      required: true
      description: the ID of article
      example: d91aa0cd-61d6-83cc-41bb-8d5656e130f7
      schema:
        type: string
        format: uuid

    citizen:
      name: citizen
      in: path
      description: ID of citizen
      example: 6434f4f9-f570-f22a-c134-8668350651ff
      required: true
      schema:
        type: string
        format: uuid

    comment:
      name: comment
      in: path
      description: The ID of comment
      example: 701dc504-db49-7e3a-2c0a-32542507ea57
      required: true
      schema:
        type: string
        format: uuid

  responses:
    401:
      description: Unautorized
      content:
        application/json:
          schema:
            description: noting

  schemas:
    UUID:
      type: string
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
      description: UUID
      format: uuid
      example:
        e74be8e4-6823-47c4-bd1b-789725b2fa8e
    UuidEntity:
      properties:
        id:
          $ref: '#/components/schemas/UUID'
    Paginated:
      properties:
        result:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/UuidEntity'
        count:
          type: integer
          minimum: 0
          example: 1
        currentPage:
          type: integer
          minimum: 0
          example: 1
        limit:
          type: integer
          minimum: 0
          maximum: 50
          example: 50
        offset:
          type: integer
          minimum: 0
          example: 1
        total:
          type: integer
          minimum: 0
          example: 1
    ArticleResponse:
      additionalProperties: false
      required:
        - id
        - versionId
        - versionNumber
        - title
        - anonymous
        - content
        - description
        - tags
        - draft
        - lastVersion
        - createdBy
        - views
        - opinions
        - votes
      properties:
        id:
          type: string
          format: uuid
        versionId:
          type: string
          format: uuid
        versionNumber:
          type: integer
          minimum: 0
        title:
          type: string
        anonymous:
          type: boolean
        content:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        draft:
          type: boolean
        lastVersion:
          type: boolean
        createdAt:
          type: string
          format: 'date-time'
        createdBy:
          type: object
          additionalProperties: false
          required:
            - id
            - name
            - email
          properties:
            id:
              type: string
              format: uuid
            name:
              type: object
              required:
                - firstName
                - lastName
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
            email:
              type: string
        workgroup:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        views:
          additionalProperties: false
          required:
            - total
            - unique
          properties:
            total:
              type: integer
            unique:
              type: integer
        opinions:
          additionalProperties:
            type: integer
          example:
            'good writed': 5
            'to short': 19
        votes:
          additionalProperties: false
          required:
            - up
            - neutral
            - down
            - total
            - score
          properties:
            up:
              type: integer
            neutral:
              type: integer
            down:
              type: integer
            total:
              type: integer
            score:
              type: integer

    CitizenListResponse:
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: object
          required:
            - firstName
            - lastName
          properties:
            firstName:
              type: string
              example:
                john
            lastName:
              type: string
              example:
                Doe
        email:
          type: string
          format: email
          example: my.email@dc-project.fr
    CitizenResponse:
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - email
        - createdAt
        - user
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: object
          required:
            - firstName
            - lastName
          properties:
            firstName:
              type: string
              example:
                john
            lastName:
              type: string
              example:
                Doe
        email:
          type: string
          format: email
          example: my.email@dc-project.fr
        birthday:
          type: string
          format: 'date'
          example: '1984-12-25'
        createdAt:
          type: string
          format: 'date-time'
        user:
          type: object
          required:
            - username
          properties:
            username:
              type: string
              example:
                john-doe
    CitizenCreator:
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - user
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: object
          required:
            - firstName
            - lastName
          properties:
            firstName:
              type: string
              example:
                john
            lastName:
              type: string
              example:
                Doe
        user:
          type: object
          required:
            - username
          properties:
            username:
              type: string
              example:
                john-doe

    CommentResponse:
      additionalProperties: false
      type: object
      required:
        - id
        - content
        - parent
        - createdAt
        - createdBy
        - votes
        - target
        - childrenCount
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        content:
          type: string
          example:
            Lorem ipsum...
        parent:
          nullable: true
          properties:
            id:
              $ref: '#/components/schemas/UUID'
            reference:
              type: string
        createdBy:
          $ref: '#/components/schemas/CitizenCreator'
        createdAt:
          type: string
          format: 'date-time'
        target:
          additionalProperties: false
          properties:
            id:
              $ref: '#/components/schemas/UUID'
            reference:
              type: string
        childrenCount:
          type: integer
          minimum: 0
        votes:
          properties:
            up:
              type: number
              minimum: 0
            neutral:
              type: number
              minimum: 0
            down:
              type: number
              minimum: 0
            total:
              type: number
              minimum: 0
            score:
              type: number

  securitySchemes:
    JWTAuth:
      type: http
      scheme: bearer
      description: call /login to get token
      bearerFormat: JWT

servers:
  - description: localhost
    url: http://localhost:8080
  - description: production
    url: http://dc-project.fr