OpenAPI version 3.0 for Swagger Editor & Swagger UI - Exemple

openapi.yaml

#### INFOS ####
openapi: "3.0.0"
info:
  version: <PROJET VERSION>
  title: <PROJET NAME>
  description: >-
    Multiline description allowed.
    <br/>
    <br/>
    Lines jumps using `<br/>` are also possibles and Markdown
    utilization is authorized.
    <br/>
    <br/>
    **Bulleted list:**

    * Bullet N°1

    * Bullet N°2


  termsOfService: http://example.com/terms/
  contact:
    email: [email protected]
  license:
    name: Copyright Or Not?
    url: https://domain.tld/license



#### SERVER URL ####
servers:
  - url: https://api.domain.tld/v1.0.0/



#### CATEGORIES ####
tags:
  - name: <CATEGORY NAME>
    description: <CATEGORY DESCRIPTION>



#### AUTRES INFORMATIONS ####
externalDocs:
  description: Something else?
  url: https://www.anotherdomain.tld



#### API ####
paths:

  #### <CATEGORY NAME> ####
  /users:
    get:
      summary: List all users (Cannot use markdown here).
      description: >-
        Description of this API endpoint.
      tags:
        - <CATEGORY NAME>
      security:
        # Authorization: Bearer? (https://swagger.io/docs/specification/authentication/)
        - bearerAuth: []
      parameters:
        - in: query
          name: offset
          schema:
            type: integer
          required: false
          description: >-
            Start sending users from `offset`: (e.g.) `GET [...]/users?offset=100`.
        - in: query
          name: limit
          schema:
            type: integer
          required: false
          description: >-
            Start sending users from `offset`, with a limit: (e.g.) `GET [...]/users?offset=100&limit=200`.
      responses:
        200:
          description: >-
            Arrow of users.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Users"
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'

    post:
      summary: Create a user.
      tags:
        - <CATEGORY NAME>
      security:
        - bearerAuth: []
      requestBody:
        description: >-
          Object that contain user's informations.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        201:
          description: >-
            User created, userID sent as response in Location header.
          headers:
            Location:
              $ref: "#/components/schemas/LocationHeader"
        202:
          description: >-
            User already exist, userID sent as response in Location header.
          headers:
            Location:
              $ref: "#/components/schemas/LocationHeader"
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'

  /users/{userID}:
    delete:
      summary: Delete a user.
      description: >-
        You can call GET /users in order to get the `userID`.
      tags:
        - <CATEGORY NAME>
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: userID
          schema:
            type: string
          required: true
          description: User ID.
      responses:
        204:
          description: >-
            User deleted.
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'

    put:
      summary: Update a user.
      tags:
        - <CATEGORY NAME>
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: userID
          schema:
            type: string
          required: true
      requestBody:
        description: >-
          An object with the updated user informations is needed :

          * Remove all fields that must not be updated

          * Set fields to `null` in order to delete it


          **Only fields from `CreateUser` are allowed.**
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        200:
          $ref: '#/components/responses/OK'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'




components:

  #### API RESPONSES ####
  responses:

    OK:
      description: OK.
      content:
        application/json:
          schema:
            required:
              - message
            properties:
              message:
                type: string
                description: Success.

    NotFound:
      description: Cannot found requested ressource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    UnauthorizedError:
      description: You are not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Forbidden:
      description: You are authenticated, but don't have the correct rights.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    TooManyRequests:
      description: Too much requests, your limit is over.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalServerError:
      description: Internal system error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'



  #### SCHEMAS ####
  schemas:

    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: >-
            Error unique ID.
        message:
          type: string
          description: >-
            Error title.
        description:
          type: string
          description: >-
            Error description.

    Users:
      type: array
      items:
        $ref: '#/components/schemas/User'
      description: >
        Arrow of users (`User`)

    User:
      type: object
      required:
        - userID
        - name
        - surname
        - email
        - password
      properties:
        userID:
          type: string
        name:
          type: string
        familyName:
          type: string
        email:
          type: string
        rights:
          type: string
          enum:
            - user
            - admin
          description: >
            rights:
             * `user` - Default
             * `admin` - All rights
        blocked:
          type: boolean
          description: >
            enable:
              * `false` - Default
              * `true` - User blocked
        emailVerified:
          type: boolean
        metadata:
          type: object
          properties:
            created:
              type: object
              properties:
                by:
                  type: string
                date:
                  type: string
                  description: Format UTC

            lastLogin:
              type: object
              properties:
                date:
                  type: string
                  description: Format UTC
                ip:
                  type: string
                sucess:
                  type: boolean
                count:
                  type: integer
                  description: >
                    Compter le nombre de connexions infructueuses
                    (si success = false)
            loginsCount:
              type: integer
            passwordReset:
              type: object
              properties:
                inProgress:
                  type: boolean
                date:
                  type: string
                  description: Format UTC
                confirmed:
                  type: boolean
                  description: >
                    L'utilisateur doit confirmer par mail la réinitialisation.
                    S'il se connecte, elle est annulée.

    CreateUser:
      type: object
      required:
        - name
        - familyName
        - email
        - password
      properties:
        name:
          type: string
        familyName:
          type: string
        email:
          type: string
        password:
          type: string
        rights:
          type: string
          enum:
            - user
            - admin
          description: >
            rights:
             * `user` - Default
             * `admin` - All rights
        blocked:
          type: boolean
          description: >
            enable:
              * `false` - Default
              * `true` - User blocked
        emailVerified:
          type: boolean

    LocationHeader:
      type: string
      description: >
        Path to the new ressource.



  #### SECURITE ####
  securitySchemes:

    AuthHeader:
      type: http
      scheme: bearer
      bearerFormat: UUID

Exemple of this file, in Swagger Editor :