Ejemplo de documento Swagger

A continuación se muestra un ejemplo completo de documento Swagger, que es una especificación detallada de una API de sistema de gestión de usuarios.

Este documento describe una API de sistema de gestión de usuarios, que incluye información básica del usuario, servicio de autenticación, modelo de datos, etc.

Esta API sigue el estilo RESTful y utiliza el formato JSON para el intercambio de datos.

Podemos usar Swagger Editor para probar tu documento en línea. La dirección en línea es:https://editor.swagger.io/Solo tienes que copiar y pegar tu YAML o JSON en el editor, y el panel derecho mostrará el documento de API visualizado.

Ejemplo

openapi: 3.0.0
info:
  title:Mi primera API
  description: |
Este es un documento de ejemplo de API simple que muestra las funciones básicas del sistema de gestión de usuarios.
Incluye operaciones de consulta, creación, actualización y eliminación de usuarios.
  version: 1.0.0
  contact:
    name:Equipo de soporte de API
    email: support@example.com
    url: https://www.example.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: https://api.example.com/v1
    description:Entorno de producción
  - url: https://staging-api.example.com/v1
    description:Entorno de preproducción
  - url: https://dev-api.example.com/v1
    description:Entorno de desarrollo

tags:
  - name:Usuario
    description:Operaciones relacionadas con la gestión de usuarios
  - name:Autenticación
    description:Operaciones relacionadas con la autenticación

paths:
  /users:
    get:
      tags:
        -Usuario
      summary:Obtener lista de todos los usuarios
      description:Devuelve la información de todos los usuarios del sistema, con soporte para paginación y filtrado.
      operationId: getUsers
      parameters:
        - name: limit
          in: query
          description:Número máximo de resultados devueltos
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description:Desplazamiento de paginación
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: status
          in: query
          description:Filtrar por estado de usuario
          required: false
          schema:
            type: string
            enum: [active, inactive, banned]
      responses:
        '200':
          description:Lista de usuarios obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description:Número total de usuarios
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
              example:
                total: 2
                users:
                  - id: 1
                    username: "john_doe"
                    email: "john@example.com"
                    status: "active"
                    createdAt: "2023-05-01T12:00:00Z"
                  - id: 2
                    username: "jane_smith"
                    email: "jane@example.com"
                    status: "active"
                    createdAt: "2023-05-02T14:30:00Z"
        '400':
          description:Solicitud no válida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []
   
    post:
      tags:
        -Usuario
      summary:Crear nuevo usuario
      description:Crea un nuevo usuario en el sistema
      operationId: createUser
      requestBody:
        description:Información del usuario
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
            example:
              username: "new_user"
              email: "new_user@example.com"
              password: "securePassword123"
      responses:
        '201':
          description:Usuario creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 3
                username: "new_user"
                email: "new_user@example.com"
                status: "active"
                createdAt: "2023-05-10T09:15:00Z"
        '400':
          description:Solicitud no válida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 400
                message: "Formato de correo electrónico incorrecto"
        '409':
          description:Conflicto de recursos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 409
                message: "El nombre de usuario ya existe"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []

  /users/{userId}:
    parameters:
      - name: userId
        in: path
        description:ID de usuario
        required: true
        schema:
          type: integer
          format: int64
   
    get:
      tags:
        -Usuario
      summary:Obtener usuario específico
      description:Obtiene la información detallada de un usuario específico según su ID
      operationId: getUserById
      responses:
        '200':
          description:Información del usuario obtenida exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
              example:
                id: 1
                username: "john_doe"
                email: "john@example.com"
                firstName: "John"
                lastName: "Doe"
                phone: "+1234567890"
                status: "active"
                createdAt: "2023-05-01T12:00:00Z"
                lastLogin: "2023-05-10T08:30:00Z"
        '404':
          description:El usuario no existe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 404
                message: "El usuario no existe"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []
   
    put:
      tags:
        -Usuario
      summary:Actualizar información del usuario
      description:Actualiza la información de un usuario específico
      operationId: updateUser
      requestBody:
        description:Información del usuario a actualizar
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
            example:
              firstName: "Jonathan"
              lastName: "Doe"
              phone: "+1987654321"
      responses:
        '200':
          description:Información del usuario actualizada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          description:Solicitud no válida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description:El usuario no existe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []
   
    delete:
      tags:
        -Usuario
      summary:Eliminar usuario
      description:Elimina un usuario específico del sistema
      operationId: deleteUser
      responses:
        '204':
          description:Usuario eliminado exitosamente
        '404':
          description:El usuario no existe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []

  /auth/login:
    post:
      tags:
        -Autenticación
      summary:Inicio de sesión de usuario
      description:El usuario inicia sesión y obtiene un token de acceso
      operationId: login
      requestBody:
        description:Credenciales de inicio de sesión
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description:Nombre de usuario
                password:
                  type: string
                  format: password
                  description:Contraseña
              required:
                - username
                - password
            example:
              username: "john_doe"
              password: "password123"
      responses:
        '200':
          description:Inicio de sesión exitoso
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                    description:Token de acceso JWT
                  tokenType:
                    type: string
                    description:Tipo de token
                  expiresIn:
                    type: integer
                    description:Tiempo de expiración del token (segundos)
              example:
                accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                tokenType: "Bearer"
                expiresIn: 3600
        '401':
          description:Inicio de sesión fallido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 401
                message: "Nombre de usuario o contraseña incorrectos"

  /auth/register:
    post:
      tags:
        -Autenticación
      summary:Registro de usuario
      description:Registra un nuevo usuario y obtiene un token de acceso
      operationId: register
      requestBody:
        description:Información de registro
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        '201':
          description:Registro exitoso
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  accessToken:
                    type: string
                    description:Token de acceso JWT
              example:
                user:
                  id: 3
                  username: "new_user"
                  email: "new_user@example.com"
                  status: "active"
                  createdAt: "2023-05-10T09:15:00Z"
                accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        '400':
          description:Solicitud no válida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description:El usuario ya existe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description:Identificador único del usuario
        username:
          type: string
          description:Nombre de usuario
        email:
          type: string
          format: email
          description:Correo electrónico del usuario
        status:
          type: string
          enum: [active, inactive, banned]
          description:Estado del usuario
        createdAt:
          type: string
          format: date-time
          description:Fecha de creación
      required:
        - id
        - username
        - email
        - status
   
    UserDetail:
      allOf:
        - $ref: '#/components/schemas/User'
        - type: object
          properties:
            firstName:
              type: string
              description:Nombre
            lastName:
              type: string
              description:Apellido
            phone:
              type: string
              description:Número de teléfono
            lastLogin:
              type: string
              format: date-time
              description:Última hora de inicio de sesión
   
    NewUser:
      type: object
      properties:
        username:
          type: string
          description:Nombre de usuario
          minLength: 3
          maxLength: 50
        email:
          type: string
          format: email
          description:Correo electrónico del usuario
        password:
          type: string
          format: password
          description:Contraseña del usuario
          minLength: 8
          maxLength: 100
        firstName:
          type: string
          description:Nombre
        lastName:
          type: string
          description:Apellido
        phone:
          type: string
          description:Número de teléfono
      required:
        - username
        - email
        - password
   
    UpdateUser:
      type: object
      properties:
        email:
          type: string
          format: email
          description:Correo electrónico del usuario
        firstName:
          type: string
          description:Nombre
        lastName:
          type: string
          description:Apellido
        phone:
          type: string
          description:Número de teléfono
        password:
          type: string
          format: password
          description:Nueva contraseña (si se desea cambiar)
          minLength: 8
          maxLength: 100
   
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description:Código de error
        message:
          type: string
          description:Mensaje de error
      required:
        - code
        - message

  responses:
    UnauthorizedError:
      description:Token de acceso perdido o no válido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: "Acceso no autorizado"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description:Autenticación mediante token Bearer JWT

security:
  - bearerAuth: []

A continuación se presentan los componentes principales del documento:

1. Sección de información básica

  • Título y descripción de la API: funciones básicas del sistema de gestión de usuarios
  • Información de versión:1.0.0
  • Información de contacto: información de contacto del equipo de soporte de API
  • Licencia:Apache 2.0

2. Configuración del servidor

  • Entorno de producción
  • Entorno de preproducción
  • Entorno de desarrollo

3. Clasificación de etiquetas de API

  • Operaciones relacionadas con usuarios
  • Operaciones relacionadas con autenticación

4. Rutas y operaciones

Esta API incluye los siguientes endpoints:

Gestión de usuarios

  • GET /users- Obtener lista de todos los usuarios (con soporte para paginación y filtrado)
  • POST /users- Crear nuevo usuario
  • GET /users/{userId}- Obtener detalles de un usuario específico
  • PUT /users/{userId}- Actualizar información del usuario
  • DELETE /users/{userId}- Eliminar usuario

Servicio de autenticación

  • POST /auth/login- Inicio de sesión de usuario
  • POST /auth/register- Registro de usuario

5. Modelo de datos

  • User- Información básica del usuario
  • UserDetail- Información detallada del usuario
  • NewUser- Cuerpo de solicitud para crear usuario
  • UpdateUser- Cuerpo de solicitud para actualizar usuario
  • Error- Respuesta de error

6. Definición de seguridad

Utiliza token Bearer JWT para la autenticación de la API.

Este documento sigue la especificación OpenAPI 3.0.0, e incluye parámetros de solicitud completos, códigos de estado de respuesta, definiciones de modelos de datos y valores de ejemplo. Puedes copiar este documento YAML en Swagger Editor para ver el efecto visualizado, o integrarlo en tu proyecto.

Este documento puede servir como base para desarrollar tu API RESTful, y se puede ampliar y mejorar a medida que el proyecto evolucione.

Otras extensiones