Articles

Swagger OpenAPI Best Practices: Structure and Naming (2026)

April 6, 2026 5 min read

The OpenAPI Specification, often referred to as Swagger, is a language-agnostic, standardized format for describing RESTful APIs. It allows both humans and machines to understand the capabilities of an API without needing to access the source code, documentation, or network traffic. A well-structured and consistently named OpenAPI document is crucial for its effectiveness, impacting everything from developer adoption to automated tooling.

Structure Best Practices

1. Single Source of Truth: Your OpenAPI document should be the definitive description of your API. Avoid having multiple, potentially conflicting versions. This means generating it directly from your code (if using frameworks that support it) or maintaining it diligently as the single source of truth.

2. Versioning: API versioning is essential for managing changes without breaking existing clients.

  • URL Path Versioning: This is the most common approach. Include the version number directly in the URL path.
    paths:
  /v1/users:
    get:
      summary: Get a list of users
      operationId: getUsersV1
      responses:
        '200':
          description: A list of users
/v2/users:
  get:
    summary: Get a list of users (new version)
    operationId: getUsersV2
    responses:
      '200':
        description: A list of users
  • Header Versioning: While less common for direct user interaction, it’s an option for internal services.
  • Consider Semantic Versioning: For your API, and reflect that in your OpenAPI version.

3. Grouping by Resource: Organize your paths object by the API resource they represent. This makes navigation intuitive.

yaml paths: /users: get: summary: List users post: summary: Create a user /users/{userId}: get: summary: Get a user by ID put: summary: Update a user delete: summary: Delete a user /products: get: summary: List products post: summary: Create a product

4. Use $ref for Reusability: Define common components like schemas, parameters, and responses in the components section and reference them throughout your document. This reduces redundancy and improves maintainability.

yaml openapi: 3.0.0 info: title: Example API version: 1.0.0 paths: /users: get: summary: Get users responses: '200': description: A list of users content: application/json: schema: $ref: '#/components/schemas/UserList' components: schemas: UserList: type: array items: $ref: '#/components/schemas/User' User: type: object properties: id: type: integer name: type: string

5. Clear and Concise summary and description:

  • summary: A short, imperative sentence describing the operation.
  • description: A more detailed explanation, including any business logic, side effects, or important considerations.

6. Consistent Tagging: Use tags to group operations logically, often mirroring the resource structure. This is what appears in tools like Swagger UI.

yaml paths: /users: get: summary: List users tags: - Users /products: get: summary: List products tags: - Products

Naming Best Practices

1. Path Naming:

  • Use Plural Nouns: For collections of resources (e.g., /users, /products).
  • Use Resource ID for Specific Instances: For individual resources (e.g., /users/{userId}, /products/{productId}).
  • Avoid Verbs: The HTTP method (GET, POST, PUT, DELETE) already implies the action. /users/get is redundant; /users with a GET method is sufficient.
  • Be Consistent: Stick to a convention (e.g., all lowercase, kebab-case). Lowercase is most common.

2. Parameter Naming:

  • Path Parameters: Use the same name as the placeholder in the path (e.g., userId in /users/{userId}).
  • Query Parameters: Be descriptive and specific. Use camelCase.
    • Good: pageNumber, pageSize, sortBy, sortOrder, filterByStatus
    • Avoid: p, s, sort, filter
  • Header Parameters: Use standard HTTP header names or descriptive custom names (e.g., X-Request-ID, Authorization).
  • Body Parameters: Usually, the requestBody schema defines the structure, so individual parameter names within the body are defined in the schema.

3. Operation ID (operationId):

  • Unique and Descriptive: This ID is used by code generators. It should uniquely identify an operation.
  • Convention: A common convention is verbResource (e.g., getUser, listProducts, updateOrder). If you have versioning, consider including it: getUserV2.
  • Avoid Special Characters: Stick to alphanumeric characters and underscores.

4. Schema Naming (components/schemas):

  • Singular Nouns for Objects: Name schemas after the resource they represent (e.g., User, Product, Order).
  • Plural Nouns for Collections (Optional): Sometimes, you might have a schema specifically for a list, like UserList, ProductCollection. However, often, an array of the singular object schema is sufficient (e.g., type: array, items: {$ref: '#/components/schemas/User'}).
  • Use PascalCase: This is a common convention for schema names.

5. Property Naming within Schemas:

  • CamelCase: This is the de facto standard for JSON properties.
    • Good: firstName, lastName, orderDate, totalAmount
    • Avoid: FIRST_NAME, first_name

Example Snippet Illustrating Naming and Structure:

openapi: 3.0.0
info:
  title: E-commerce API
  version: 2.1.0
  description: API for managing products and orders.
servers:
  - url: https://api.example.com/v2
tags:
  - name: Products
    description: Operations related to products.
  - name: Orders
    description: Operations related to orders.

paths:
  /products:
    get:
      tags:
        - Products
      summary: List all products
      operationId: listProductsV2
      parameters:
        - name: limit
          in: query
          description: Maximum number of products to return.
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          description: Number of products to skip.
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: A list of products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '400':
          description: Invalid query parameters.

    post:
      tags:
        - Products
      summary: Create a new product
      operationId: createProductV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewProduct'
      responses:
        '201':
          description: Product created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Invalid request body.

  /products/{productId}:
    get:
      tags:
        - Products
      summary: Get a product by ID
      operationId: getProductByIdV2
      parameters:
        - name: productId
          in: path
          required: true
          description: The ID of the product to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: Product details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found.

components:
  schemas:
    ProductList:
      type: array
      items:
        $ref: '#/components/schemas/Product'

    Product:
      type: object
      properties:
        productId:
          type: string
          description: Unique identifier for the product.
        name:
          type: string
          description: The name of the product.
        description:
          type: string
          description: Detailed description of the product.
        price:
          type: number
          format: float
          description: The price of the product.
        availableStock:
          type: integer
          description: Number of items currently in stock.
      required:
        - productId
        - name
        - price

    NewProduct:
      type: object
      properties:
        name:
          type: string
          description: The name of the product.
        description:
          type: string
          description: Detailed description of the product.
        initialStock:
          type: integer
          description: Initial stock quantity for the new product.
      required:
        - name
        - price
        - initialStock

By adhering to these structural and naming conventions, you create an OpenAPI document that is not only technically correct but also a pleasure for developers and machines to consume, leading to better API integration and faster development cycles. The next challenge is often managing the lifecycle of your OpenAPI document as your API evolves, leading into concepts of API governance and automated validation.

More Deep Dives in Swagger

Want structured learning?

Take the full Swagger course →