Расширенные возможности Swagger

Использование components для повторного использования определений

Повторное использование схемы (модели данных)

components позволяют определять элементы, которые можно повторно использовать во всей документации API, уменьшая дублирование и обеспечивая согласованность:

Пример

components:
  schemas:
    Пользователь:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string

Ссылочный метод:

Пример

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description:Информация о пользователе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Повторное использование параметров (общих параметров)

Определите общие параметры:

Пример

components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      description:Номер страницы
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 10
      description:Записей на странице

Ссылочный метод:

Пример

paths:
  /products:
    get:
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'

Повторное использование ответов (общих ответов)

Определите стандартные ответы:

Пример

components:
  responses:
    NotFound:
      description:Ресурс не найден
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                пример: 404
              message:
                type: string
                example: "Ресурс не существует"
    BadRequest:
      description:Ошибка параметра запроса
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                пример: 400
              message:
                type: string

Ссылочный метод:

Пример

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description:Успешно
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'

Управление версиями API

Различение версий с помощью servers

Пример

servers:
  - url: https://api.example.com/v1
    description: API v1
  - url: https://api.example.com/v2
    description: API v2

Различать версии по пути

Пример

paths:
  /v1/users:
    get:
# v1 пользовательский интерфейс...
 
  /v2/users:
    get:
# v2 пользовательский интерфейс...

Различать версии по заголовкам запроса

Пример

paths:
  /users:
    get:
      parameters:
        - name: api-version
          in: header
          required: true
          schema:
            type: string
            enum: ['1.0', '2.0']

Симуляция mock-данных

Использование примеров для определения образцов данных

Определите примеры в ответе:

Пример

paths:
  /users:
    get:
      responses:
        '200':
          description:Список пользователей
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              examples:
                userList:
                  summary:Пример списка пользователей
                  value:
                    - id: 1
                      username: "user1"
                      email: "[email protected]"
                    - id: 2
                      username: "user2"
                      email: "[email protected]"

Использование функции Mock в Swagger UI

Swagger UI интегрирует mock-сервер, который может генерировать mock-ответы на основе вашего OpenAPI-определения.

Настройте mockServer в Swagger UI:

Пример

SwaggerUI({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  пресеты: [
    SwaggerUI.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUI.plugins.MockPlugin
  ],
  mockImplementations: {
    '/users': {
      get: () => ({
        status: 200,
        body: [
          { id: 1, name: "Тестовый пользователь 1" },
          { id: 2, name: "Тестовый пользователь 2" }
        ]
      })
    }
  }
})

Использование сторонних Mock-сервисов

  • Prism: Mock-сервер OpenAPI
  • Mockoon: инструмент для макетирования API, который может интегрироваться со Swagger
  • Postman: предоставляет функциональность Mock-сервера

Расширенная конфигурация безопасности

Определите несколько методов аутентификации:

Пример

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    OAuth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.com/oauth/authorize
          scopes:
            read:Разрешение на чтение
            write:Разрешение на запись

Примените определения безопасности:

Пример

безопасность:
  - bearerAuth: []
  - apiKeyAuth: []

paths:
  /users:
    get:
      безопасность:
        - OAuth2: [read]

Разделение и организация документов

Используйте$refдля ссылки на внешние файлы:

Пример

paths:
  /users:
    $ref: './paths/users.yaml'
  /products:
    $ref: './paths/products.yaml'

components:
  schemas:
    Пользователь:
      $ref: './schemas/user.yaml'

Теги и группировка

Используйте теги для организации конечных точек API:

Пример

tags:
  - name: users
    description:Управление пользователями
  - name: products
    description:Управление продуктами

paths:
  /users:
    get:
      tags:
        - users
  /products:
    get:
      tags:
        - products

Поля расширения

С помощьюx-Добавьте пользовательские свойства с префиксом:

Пример

lpaths:
  /users:
    get:
      x-controller: UserController
      x-rate-limit: 100
      x-deprecated: false

Эти расширенные возможности помогут вам создавать более структурированную, поддерживаемую и профессиональную документацию API.

Другие расширения