¿Cuáles son las buenas prácticas para las convenciones de nomenclatura en documentos OpenAPI? #

La nomenclatura es una de las decisiones de diseño más importantes en un documento OpenAPI. Los nombres aparecen en la documentación generada, en los SDK y clientes generados, en las interfaces de exploración de API y en las referencias internas de todo el documento. Una mala nomenclatura genera confusión, hace que el código generado resulte torpe y transmite inconsistencia a quienes consumen la API. Una buena nomenclatura es coherente, predecible y significativa. Este artículo reúne las buenas prácticas para cada uno de los elementos principales que se nombran en un documento OpenAPI.

Nomenclatura de rutas #

Las rutas de la API son el elemento más visible de la nomenclatura: aparecen en cada llamada a la API y en toda la documentación.

Usa palabras en minúsculas separadas por guiones #

# Good
/user-profiles/{userId}
/payment-methods/{methodId}

# Avoid
/UserProfiles/{userId}
/payment_methods/{methodId}

Las rutas en minúsculas con palabras separadas por guiones (kebab-case) son la convención más extendida y son compatibles con todos los frameworks y clientes HTTP. Las rutas con mayúsculas y minúsculas mezcladas crean una complejidad innecesaria, ya que técnicamente las rutas HTTP distinguen entre mayúsculas y minúsculas, pero los usuarios suelen esperar que no lo hagan.

Usa sustantivos para los recursos, no verbos #

Los métodos HTTP expresan la acción; las rutas expresan el recurso:

# Good
GET /orders           # List orders
POST /orders          # Create an order
GET /orders/{id}      # Get a specific order
DELETE /orders/{id}   # Delete an order

# Avoid
GET /getOrders
POST /createOrder
DELETE /deleteOrder/{id}

El nombre del recurso debe ser un sustantivo (o una frase nominal) que represente el concepto, no la operación que se realiza sobre él.

Usa sustantivos en plural para las colecciones #

Las colecciones de recursos deben usar sustantivos en plural:

# Good
/users
/products
/payment-methods

# Avoid
/user
/product
/payment-method

Los sustantivos en plural dejan claro que se está accediendo a una colección y crean un patrón coherente: GET /users devuelve una lista; GET /users/{id} devuelve un solo elemento.

Parámetros de ruta #

Los nombres de los parámetros de ruta deben usar camelCase y describir con exactitud qué identifican:

# Good
/users/{userId}
/orders/{orderId}/items/{itemId}

# Avoid
/users/{id}            # 'id' is ambiguous in nested contexts
/orders/{order_id}     # snake_case in path params is inconsistent
/users/{user}          # doesn't communicate it's an ID

Usar {userId} en lugar de {id} es especialmente importante en los recursos anidados, donde varios parámetros {id} resultarían ambiguos.

ID de operación #

El campo operationId identifica de forma única cada operación del documento. Tiene un impacto directo en los nombres de los métodos de los SDK generados:

paths:
  /users:
    get:
      operationId: listUsers          # Good: verb + noun
    post:
      operationId: createUser         # Good: verb + noun
  /users/{userId}:
    get:
      operationId: getUser            # Good
    put:
      operationId: updateUser         # Good
    delete:
      operationId: deleteUser         # Good
  /users/{userId}/addresses:
    get:
      operationId: listUserAddresses  # Good: includes parent resource context
    post:
      operationId: createUserAddress  # Good

Reglas para los ID de operación #

• Usa camelCase
• Utiliza siempre un patrón de verbo + sustantivo: getUser, listOrders, createPaymentMethod, deleteAccount
• Nunca reutilices un ID de operación (deben ser únicos en todo el documento)
• Incluye el contexto del recurso padre en las operaciones anidadas: listUserOrders, y no solo listOrders, cuando la operación está bajo /users/{userId}/orders
• Evita las abreviaturas: listApplications en lugar de listApps

Los ID de operación que siguen estas convenciones producen SDK generados con nombres de métodos legibles y predecibles: client.users.list(), client.users.create(), client.users.get(userId).

Nombres de esquemas #

Los nombres de los esquemas aparecen como nombres de tipos en el código generado, por lo que son uno de los elementos de nomenclatura más cercanos a los desarrolladores.

Usa PascalCase para los nombres de esquemas #

components:
  schemas:
    User: ...              # Good
    UserProfile: ...       # Good
    PaymentMethod: ...     # Good
    CreateUserRequest: ... # Good
    UserListResponse: ...  # Good

    user: ...              # Bad: lowercase
    user_profile: ...      # Bad: snake_case
    PAYMENT_METHOD: ...    # Bad: screaming snake case

Los nombres de esquemas en PascalCase producen nombres de clases y tipos idiomáticos en la mayoría de los lenguajes generados: User en TypeScript, User en Python, User en Java y Go.

Usa nombres descriptivos y autoexplicativos #

Los nombres de los esquemas deben describir lo que representan sin necesidad de consultar la documentación:

# Good: clear purpose and context
UserProfile
CreateOrderRequest
OrderListResponse
PaymentMethodSummary
AddressDetail
ApiError

# Avoid: vague or context-free
Data
Object
Info
Response
Input

Separa los esquemas de solicitud y de respuesta cuando sean distintos #

Cuando la forma de un recurso difiere entre la entrada y la salida (por ejemplo, id y createdAt los genera el servidor y no deben aparecer en los cuerpos de solicitud), usa esquemas independientes:

components:
  schemas:
    CreateUserRequest:
      type: object
      required: [email, name]
      properties:
        email:
          type: string
        name:
          type: string

    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time

Reutilizar el mismo esquema para la entrada y la salida da lugar a esquemas con campos opcionales que en realidad son obligatorios en la salida, lo que genera confusión en el código generado.

Nombres de parámetros #

Los nombres de los parámetros de consulta, de encabezado y de cookie deben seguir las convenciones propias de su ubicación:

• Parámetros de consulta: camelCase (pageSize, sortBy, filterStatus)
• Parámetros de ruta: camelCase (userId, orderId)
• Encabezados de solicitud: capitalización convencional de HTTP (Authorization, X-Request-Id, X-Api-Key)

Evita usar convenciones distintas para el mismo parámetro lógico en diferentes endpoints (por ejemplo, page_size en un endpoint y pageSize en otro).

Nombres de etiquetas #

Las etiquetas organizan las operaciones en grupos dentro de la documentación y del código generado. Los nombres de las etiquetas deben ser:

• En formato de título: User Management, Payment Methods, Orders
• O palabras sueltas en PascalCase: Users, Payments, Orders
• Coherentes en todas las operaciones que comparten una misma agrupación lógica

Usa la sección tags en la raíz del documento para proporcionar una descripción de cada etiqueta:

tags:
  - name: Users
    description: Operations for managing user accounts and profiles
  - name: Orders
    description: Creating, retrieving, and managing customer orders
  - name: PaymentMethods
    description: Managing saved payment methods for customers

Nombres de componentes #

Todos los nombres de componentes (schemas, parameters, responses, requestBodies, headers, examples, securitySchemes) deben usar PascalCase y ser descriptivos:

components:
  parameters:
    PageSizeParam: ...
    PageCursorParam: ...
    UserIdParam: ...
  responses:
    BadRequestResponse: ...
    UnauthorizedResponse: ...
    NotFoundResponse: ...
  securitySchemes:
    BearerAuth: ...
    ApiKeyAuth: ...

Cómo aplicar las convenciones de nomenclatura con Spectral #

Spectral puede automatizar la aplicación de las convenciones de nomenclatura:

rules:
  operation-id-camel-case:
    description: operationId must be camelCase
    given: "$.paths[*][*].operationId"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  schema-names-pascal-case:
    description: Schema names must be PascalCase
    given: "$.components.schemas"
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            "^[A-Z][a-zA-Z0-9]*$": {}
          additionalProperties: false

Conclusión #

Una nomenclatura coherente y bien elegida en todo el documento OpenAPI es señal de un proceso de diseño de API maduro y centrado en quienes la consumen. Las rutas, los parámetros, los ID de operación, los nombres de esquemas y los nombres de componentes tienen efectos posteriores en la legibilidad de la documentación, la calidad de los SDK generados y la rapidez con que se incorporan nuevos desarrolladores. Establecer las convenciones de nomenclatura desde el principio, documentarlas en una guía de estilo y aplicarlas de forma automática con Spectral garantiza que la calidad de los nombres de la API se mantenga alta a medida que esta evoluciona y el equipo crece.

Última actualización: 30 de abril de 2026.