Funciones avanzadas de Swagger

Usar components para reutilizar definiciones

Reutilización de Schema (modelo de datos)

components permite definir elementos reutilizables en todo el documento de la API, reduciendo la duplicación y asegurando la consistencia:

Ejemplo

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string

Forma de referencia:

Ejemplo

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description:Información del usuario
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Reutilización de Parameters (parámetros comunes)

Definir parámetros comunes:

Ejemplo

components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      description:Número de página
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 10
      description:Registros por página

Forma de referencia:

Ejemplo

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

Reutilización de Responses (respuestas comunes)

Definir respuestas estándar:

Ejemplo

components:
  responses:
    NotFound:
      description:Recurso no encontrado
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: "El recurso no existe"
    BadRequest:
      description:Error en los parámetros de la solicitud
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string

Forma de referencia:

Ejemplo

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description:Éxito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'

Control de versiones de API

Distinguir versiones mediante servers

Ejemplo

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

Distinguir versiones mediante la ruta

Ejemplo

paths:
  /v1/users:
    get:
# Interfaz de usuario v1...
 
  /v2/users:
    get:
# Interfaz de usuario v2...

Distinguir versiones mediante la cabecera de solicitud

Ejemplo

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

Simulación de datos Mock

Usar examples para definir datos de ejemplo

Definir ejemplos en la respuesta:

Ejemplo

paths:
  /users:
    get:
      responses:
        '200':
          description:Lista de usuarios
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              examples:
                userList:
                  summary:Lista de usuarios de ejemplo
                  value:
                    - id: 1
                      username: "user1"
                      email: "[email protected]"
                    - id: 2
                      username: "user2"
                      email: "[email protected]"

Usar la función Mock de Swagger UI

Swagger UI integra un servidor de simulación que puede generar respuestas simuladas basándose en su definición de OpenAPI.

Configurar mockServer en Swagger UI:

Ejemplo

SwaggerUI({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUI.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUI.plugins.MockPlugin
  ],
  mockImplementations: {
    '/users': {
      get: () => ({
        status: 200,
        body: [
          { id: 1, name: "Test User 1" },
          { id: 2, name: "Test User 2" }
        ]
      })
    }
  }
})

Usar servicios Mock de terceros

  • Prism: servidor de simulación de OpenAPI
  • Mockoon: herramienta de simulación de API integrable con Swagger
  • Postman: ofrece funciones de servidor mock

Configuración avanzada de seguridad

Definir varios métodos de autenticación:

Ejemplo

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:Permiso de lectura
            write:Permiso de escritura

Aplicar las definiciones de seguridad:

Ejemplo

security:
  - bearerAuth: []
  - apiKeyAuth: []

paths:
  /users:
    get:
      security:
        - OAuth2: [read]

Separación y organización de documentos

Usar$refReferenciar archivos externos:

Ejemplo

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

components:
  schemas:
    User:
      $ref: './schemas/user.yaml'

Etiquetas y agrupación

Usar etiquetas para organizar los endpoints de la API:

Ejemplo

tags:
  - name: users
    description:Gestión de usuarios
  - name: products
    description:Gestión de productos

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

Campos de extensión

Mediantex-el prefijo para añadir propiedades personalizadas:

Ejemplo

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

Estas funciones avanzadas pueden ayudarle a crear documentos de API más estructurados, mantenibles y profesionales.

Otras extensiones