swl-ses 3.3.2

package/habilidades/api-rest-diseno/recursos/openapi-template.yaml

@@ -0,0 +1,506 @@
+openapi: "3.1.0"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# INSTRUCCIONES DE USO
+# Copiar este archivo a tu proyecto como docs/openapi.yaml
+# Reemplazar todos los valores entre [corchetes] con los reales.
+# Eliminar los comentarios que empiezan con # INSTRUCCIÓN antes de publicar.
+# ─────────────────────────────────────────────────────────────────────────────
+
+info:
+  title: "[Nombre del API]"
+  version: "1.0.0"
+  description: |
+    [Descripción de 2-3 oraciones: qué hace el API, quién lo consume, qué dominio cubre.]
+
+    ## Autenticación
+    Todos los endpoints (excepto los marcados con `public: true`) requieren
+    un token JWT válido en el header `Authorization: Bearer <token>`.
+
+    ## Versionado
+    Esta API sigue SemVer. Los cambios breaking incrementan el segmento MAJOR
+    del header `API-Version`.
+  contact:
+    name: "[Equipo responsable]"
+    email: "[email@empresa.com]"
+  license:
+    name: "Proprietary"
+
+servers:
+  - url: "https://api.[tu-dominio.com]/v1"
+    description: "Producción"
+  - url: "https://api-staging.[tu-dominio.com]/v1"
+    description: "Staging"
+  - url: "http://localhost:8000/v1"
+    description: "Desarrollo local"
+
+# ─── Seguridad global ──────────────────────────────────────────────────────────
+security:
+  - BearerAuth: []
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        JWT obtenido del endpoint `POST /auth/login`.
+        Expira en 24 horas. Renovar con `POST /auth/refresh`.
+
+  # ─── Schemas reutilizables ──────────────────────────────────────────────────
+  schemas:
+
+    # Paginación estándar
+    PaginatedResponse:
+      type: object
+      required: [items, total, page, page_size, pages]
+      properties:
+        items:
+          type: array
+          description: "Lista de recursos de la página actual"
+        total:
+          type: integer
+          minimum: 0
+          description: "Total de registros en todas las páginas"
+          example: 247
+        page:
+          type: integer
+          minimum: 1
+          description: "Número de página actual (base 1)"
+          example: 1
+        page_size:
+          type: integer
+          minimum: 1
+          maximum: 100
+          description: "Registros por página"
+          example: 20
+        pages:
+          type: integer
+          minimum: 0
+          description: "Total de páginas disponibles"
+          example: 13
+
+    # Error estándar
+    ErrorResponse:
+      type: object
+      required: [error, message]
+      properties:
+        error:
+          type: string
+          description: "Código de error en snake_case"
+          example: "recurso_no_encontrado"
+        message:
+          type: string
+          description: "Descripción legible del error"
+          example: "El recurso con id '550e8400' no fue encontrado"
+        details:
+          type: object
+          description: "Información adicional de diagnóstico (opcional)"
+          additionalProperties: true
+        request_id:
+          type: string
+          format: uuid
+          description: "ID único de la request para trazabilidad en logs"
+
+    # Error de validación (422)
+    ValidationErrorResponse:
+      type: object
+      required: [error, message, fields]
+      properties:
+        error:
+          type: string
+          example: "error_de_validacion"
+        message:
+          type: string
+          example: "La request contiene campos inválidos"
+        fields:
+          type: array
+          items:
+            type: object
+            required: [field, message]
+            properties:
+              field:
+                type: string
+                description: "Nombre del campo con error (usa dot notation para anidados)"
+                example: "usuario.email"
+              message:
+                type: string
+                description: "Descripción del error de validación"
+                example: "Debe ser un email válido"
+
+    # UUID reutilizable
+    UUID:
+      type: string
+      format: uuid
+      example: "550e8400-e29b-41d4-a716-446655440000"
+
+    # Timestamp ISO 8601
+    Timestamp:
+      type: string
+      format: date-time
+      example: "2026-03-25T14:32:00Z"
+
+    # ─── [Recurso principal] ─────────────────────────────────────────────────
+    # INSTRUCCIÓN: Reemplazar [Recurso] con el nombre real (ej: Factura, Usuario)
+
+    RecursoBase:
+      type: object
+      required: [id, created_at, updated_at]
+      properties:
+        id:
+          $ref: "#/components/schemas/UUID"
+        created_at:
+          $ref: "#/components/schemas/Timestamp"
+        updated_at:
+          $ref: "#/components/schemas/Timestamp"
+        created_by:
+          type: string
+          format: email
+          description: "Email del usuario que creó el registro"
+
+    RecursoCreate:
+      type: object
+      required: []  # INSTRUCCIÓN: listar campos obligatorios
+      properties:
+        nombre:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: "[Descripción del campo]"
+          example: "[Ejemplo]"
+        # INSTRUCCIÓN: agregar más campos según el dominio
+
+    RecursoUpdate:
+      type: object
+      description: "Todos los campos son opcionales (PATCH semántico)"
+      properties:
+        nombre:
+          type: string
+          minLength: 1
+          maxLength: 255
+
+    RecursoRead:
+      allOf:
+        - $ref: "#/components/schemas/RecursoBase"
+        - $ref: "#/components/schemas/RecursoCreate"
+
+  # ─── Parámetros reutilizables ────────────────────────────────────────────────
+  parameters:
+
+    PathId:
+      name: id
+      in: path
+      required: true
+      schema:
+        $ref: "#/components/schemas/UUID"
+      description: "Identificador único del recurso"
+
+    QueryPage:
+      name: page
+      in: query
+      schema:
+        type: integer
+        minimum: 1
+        default: 1
+      description: "Número de página (base 1)"
+
+    QueryPageSize:
+      name: page_size
+      in: query
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 20
+      description: "Registros por página (máximo 100)"
+
+    QuerySearch:
+      name: q
+      in: query
+      schema:
+        type: string
+        minLength: 2
+      description: "Texto de búsqueda libre (busca en campos indexados)"
+
+    QueryOrderBy:
+      name: order_by
+      in: query
+      schema:
+        type: string
+      description: |
+        Campo de ordenamiento. Prefijo `-` para orden descendente.
+        Ejemplos: `created_at`, `-created_at`, `nombre`
+
+  # ─── Respuestas reutilizables ────────────────────────────────────────────────
+  responses:
+
+    "400BadRequest":
+      description: "Request inválida"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+
+    "401Unauthorized":
+      description: "Token JWT ausente, inválido o expirado"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example:
+            error: "token_invalido"
+            message: "El token JWT es inválido o ha expirado"
+
+    "403Forbidden":
+      description: "El usuario no tiene permiso para esta operación"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example:
+            error: "permiso_denegado"
+            message: "No tienes permiso para realizar esta acción"
+
+    "404NotFound":
+      description: "El recurso no existe"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+
+    "422Unprocessable":
+      description: "Error de validación en el cuerpo de la request"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ValidationErrorResponse"
+
+    "500InternalError":
+      description: "Error interno del servidor"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example:
+            error: "error_interno"
+            message: "Ocurrió un error inesperado. Por favor contacta soporte con el request_id."
+
+# ─── Paths ────────────────────────────────────────────────────────────────────
+paths:
+
+  # INSTRUCCIÓN: Reemplazar /recursos con la ruta real del recurso en plural
+  # Mantener rutas ESTÁTICAS antes de las PARAMÉTRICAS
+
+  /recursos:
+    get:
+      operationId: "listar_recursos"
+      summary: "Listar recursos"
+      tags: ["[Nombre del recurso]"]
+      parameters:
+        - $ref: "#/components/parameters/QueryPage"
+        - $ref: "#/components/parameters/QueryPageSize"
+        - $ref: "#/components/parameters/QuerySearch"
+        - $ref: "#/components/parameters/QueryOrderBy"
+        # INSTRUCCIÓN: agregar filtros específicos del dominio
+        - name: estatus
+          in: query
+          schema:
+            type: string
+            enum: ["activo", "inactivo", "borrador"]
+          description: "Filtrar por estatus"
+      responses:
+        "200":
+          description: "Lista paginada de recursos"
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/PaginatedResponse"
+                  - type: object
+                    properties:
+                      items:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/RecursoRead"
+        "401":
+          $ref: "#/components/responses/401Unauthorized"
+        "500":
+          $ref: "#/components/responses/500InternalError"
+
+    post:
+      operationId: "crear_recurso"
+      summary: "Crear un nuevo recurso"
+      tags: ["[Nombre del recurso]"]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RecursoCreate"
+      responses:
+        "201":
+          description: "Recurso creado exitosamente"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RecursoRead"
+          headers:
+            Location:
+              description: "URL del recurso creado"
+              schema:
+                type: string
+                format: uri
+        "401":
+          $ref: "#/components/responses/401Unauthorized"
+        "403":
+          $ref: "#/components/responses/403Forbidden"
+        "422":
+          $ref: "#/components/responses/422Unprocessable"
+        "500":
+          $ref: "#/components/responses/500InternalError"
+
+  /recursos/{id}:
+    parameters:
+      - $ref: "#/components/parameters/PathId"
+
+    get:
+      operationId: "obtener_recurso"
+      summary: "Obtener un recurso por ID"
+      tags: ["[Nombre del recurso]"]
+      responses:
+        "200":
+          description: "Recurso encontrado"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RecursoRead"
+        "401":
+          $ref: "#/components/responses/401Unauthorized"
+        "404":
+          $ref: "#/components/responses/404NotFound"
+
+    patch:
+      operationId: "actualizar_recurso"
+      summary: "Actualizar parcialmente un recurso"
+      tags: ["[Nombre del recurso]"]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RecursoUpdate"
+      responses:
+        "200":
+          description: "Recurso actualizado"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RecursoRead"
+        "401":
+          $ref: "#/components/responses/401Unauthorized"
+        "403":
+          $ref: "#/components/responses/403Forbidden"
+        "404":
+          $ref: "#/components/responses/404NotFound"
+        "422":
+          $ref: "#/components/responses/422Unprocessable"
+
+    delete:
+      operationId: "eliminar_recurso"
+      summary: "Eliminar un recurso"
+      tags: ["[Nombre del recurso]"]
+      responses:
+        "204":
+          description: "Recurso eliminado — sin cuerpo de respuesta"
+        "401":
+          $ref: "#/components/responses/401Unauthorized"
+        "403":
+          $ref: "#/components/responses/403Forbidden"
+        "404":
+          $ref: "#/components/responses/404NotFound"
+
+  # ─── Autenticación (incluida como referencia) ──────────────────────────────
+  /auth/login:
+    post:
+      operationId: "login"
+      summary: "Iniciar sesión y obtener tokens JWT"
+      tags: ["Autenticación"]
+      security: []  # Endpoint público — no requiere token
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, password]
+              properties:
+                email:
+                  type: string
+                  format: email
+                password:
+                  type: string
+                  format: password
+                  minLength: 8
+      responses:
+        "200":
+          description: "Login exitoso"
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [access_token, refresh_token, expires_in]
+                properties:
+                  access_token:
+                    type: string
+                    description: "JWT de acceso. Incluir en header Authorization: Bearer <token>"
+                  refresh_token:
+                    type: string
+                    description: "Token para renovar el access_token vía /auth/refresh"
+                  expires_in:
+                    type: integer
+                    description: "Segundos hasta que expira el access_token"
+                    example: 86400
+        "401":
+          description: "Credenciales inválidas"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+
+  /auth/refresh:
+    post:
+      operationId: "refresh_token"
+      summary: "Renovar access token usando refresh token"
+      tags: ["Autenticación"]
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [refresh_token]
+              properties:
+                refresh_token:
+                  type: string
+      responses:
+        "200":
+          description: "Token renovado"
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  access_token:
+                    type: string
+                  expires_in:
+                    type: integer
+
+# ─── Tags (para agrupar endpoints en la UI) ───────────────────────────────────
+tags:
+  - name: "Autenticación"
+    description: "Endpoints para login y renovación de tokens"
+  - name: "[Nombre del recurso]"
+    description: "[Descripción del grupo de endpoints]"
+  # INSTRUCCIÓN: agregar más tags según los dominios del API