¿Cuáles son algunos ejemplos de esquemas de OpenAPI?

¿Cuáles son algunos ejemplos de esquemas de OpenAPI? #

OpenAPI, anteriormente conocido como Swagger, es un estándar para definir API RESTful de manera que tanto las personas como las computadoras puedan comprender las capacidades de un servicio sin acceder a su código fuente. Este formato es independiente del lenguaje y garantiza que las API se describan de forma legible tanto para máquinas como para humanos. Un esquema de OpenAPI define los endpoints, los parámetros, los formatos de solicitud y respuesta, las consideraciones de seguridad y cualquier otro detalle fundamental para implementar o consumir la API.

En este artículo examinaremos varios ejemplos de esquemas de OpenAPI en distintos casos de uso y sectores.

API sencilla para una aplicación de lista de tareas #

Una API de lista de tareas es un excelente punto de partida para comprender los fundamentos de OpenAPI. Incluye las operaciones CRUD típicas (Create, Read, Update, Delete; es decir, crear, leer, actualizar y eliminar).

openapi: 3.0.0
info:
  title: Simple ToDo List API
  version: 1.0.0
paths:
  /todos:
    get:
      summary: List all to-dos
      operationId: listTodos
      responses:
        '200':
          description: A JSON array of to-dos
          content:
            application/json: 
              schema: 
                type: array
                items: 
                  $ref: '#/components/schemas/ToDo'
    post:
      summary: Create a new to-do
      operationId: createTodo
      requestBody:
        description: To-do to add
        required: true
        content:
          application/json:
            schema: 
              $ref: '#/components/schemas/NewToDo'
      responses:
        '201':
          description: To-do created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToDo'
  /todos/{id}:
    get:
      summary: Get a to-do by ID
      operationId: getTodoById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single to-do
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/ToDo'
        '404':
          description: To-do not found
    put:
      summary: Update a to-do
      operationId: updateTodo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Updated to-do
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewToDo'
      responses:
        '200':
          description: To-do updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToDo'
        '404':
          description: To-do not found
    delete:
      summary: Delete a to-do
      operationId: deleteTodo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: To-do deleted
        '404':
          description: To-do not found
components:
  schemas:
    ToDo:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        completed:
          type: boolean
    NewToDo:
      type: object
      properties:
        title:
          type: string
        completed:
          type: boolean
          default: false

En este esquema:

El endpoint /todos admite los métodos GET y POST.
El endpoint /todos/{id} admite los métodos GET, PUT y DELETE para tareas específicas según su ID.
Define códigos de respuesta comunes como 200, 201, 204 y 404.
ToDo y NewToDo se definen en la sección components para evitar redundancia.

API para una plataforma de blogs #

Un ejemplo más complejo podría ser el de una plataforma de blogs. Esta API tendrá endpoints para usuarios, publicaciones y comentarios.

openapi: 3.0.0
info:
  title: Blogging Platform API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      responses:
        '200':
          description: A JSON array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /users/{userId}:
    get:
      summary: Fetch a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
  /posts:
    get:
      summary: List all posts
      operationId: listPosts
      responses:
        '200':
          description: A JSON array of posts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
  /posts/{postId}:
    get:
      summary: Fetch a post by ID
      operationId: getPostById
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          description: Post not found
  /posts/{postId}/comments:
    get:
      summary: List comments for a post
      operationId: listComments
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of comments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
    Post:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        body:
          type: string
        authorId:
          type: string
    Comment:
      type: object
      properties:
        id:
          type: string
        body:
          type: string
        postId:
          type: string
        authorId:
          type: string

En este esquema:

Los usuarios, las publicaciones y los comentarios tienen cada uno sus propios endpoints.
La sección components minimiza la redundancia.
Las rutas de los endpoints están parametrizadas para identificar los recursos.

Ejemplo de API de comercio electrónico #

Una API de comercio electrónico gestionará productos, pedidos y clientes. Este esquema será más complejo, ya que incluye parámetros de búsqueda y recursos anidados.

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
paths:
  /products:
    get:
      summary: List all products
      operationId: listProducts
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: priceMin
          in: query
          schema:
            type: number
        - name: priceMax
          in: query
          schema:
            type: number
      responses:
        '200':
          description: A JSON array of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      summary: Fetch a product by ID
      operationId: getProductById
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
  /orders:
    post:
      summary: Create a new order
      operationId: createOrder
      requestBody:
        description: Order details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{orderId}:
    get:
      summary: Fetch an order by ID
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        price:
          type: number
    NewOrder:
      type: object
      properties:
        productIds:
          type: array
          items:
            type: string
        customerId:
          type: string
    Order:
      type: object
      properties:
        id:
          type: string
        productIds:
          type: array
          items:
            type: string
        customerId:
          type: string
        status:
          type: string

En este esquema:

GET /products admite filtros mediante parámetros de consulta.
POST /orders permite crear nuevos pedidos.
La estructura admite la lógica de negocio más compleja propia de las plataformas de comercio electrónico.

Conclusión #

Los esquemas de OpenAPI ofrecen una forma estandarizada de describir las API RESTful, lo que facilita definir, desarrollar y consumir servicios. Desde sencillas listas de tareas hasta complejos sistemas de comercio electrónico, estos esquemas permiten una representación clara y concisa de todo el ciclo de vida de la API. Esto no solo ayuda a crear API sólidas, sino que también garantiza que la documentación, las bibliotecas de cliente y otras herramientas puedan generarse automáticamente, agilizando los procesos de desarrollo.

Para obtener más información sobre OpenAPI, te recomiendo visitar el sitio web oficial de la OpenAPI Initiative. Para profundizar en la propia especificación de OpenAPI, la documentación de Swagger es un excelente recurso. También puedes explorar aplicaciones prácticas y herramientas como SwaggerHub para la colaboración y el control de versiones.

Desarrollar una comprensión sólida de los esquemas de OpenAPI a través de ejemplos como estos ayuda a acortar la distancia entre los desarrolladores con conocimientos técnicos y las partes interesadas menos técnicas, lo que garantiza una gestión más fluida del ciclo de vida de la API y una mejor experiencia de desarrollo en general.

Última actualización: 29 de mayo de 2024.