openapi-docs.yml

openapi: 3.0.0
info:
  version: 1.0.0
  title: My API
  description: This is the API
servers:
  - url: v1
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    UserId:
      type: string
      example: '1212121'
    User:
      type: object
      properties:
        id:
          type: string
          example: '1212121'
        name:
          type: string
          example: John Doe
        age:
          type: number
          example: 42
      required:
        - id
        - name
        - age
  parameters:
    UserId:
      schema:
        $ref: '#/components/schemas/UserId'
      required: true
      name: id
      in: path
paths:
  '/users/{id}':
    get:
      description: Get user data by its id
      summary: Get a single user
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Object with user data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '204':
          description: No content - successful operation