APIForge

Good OpenAPI 3.0 Specification Example

Study a clean, well-structured OpenAPI 3.0 specification featuring singular collection naming, reusable error components, and explicit responses.

  • Example
  • OpenAPI
  • Published

The problem

Many teams produce incomplete OpenAPI specs with missing error responses, unmodeled request bodies, and inline repetitive schemas.

AvoidThe anti-pattern

YAMLbad-pattern.yaml
paths:
  /getUsers:
    get:
      responses:
        '200':
          description: OK

This spec uses verb-like paths (/getUsers), omits operation summaries, and doesn't model error responses.

PreferThe refactored version

YAMLgood-pattern.yaml
openapi: 3.0.3
info:
  title: User Management Service
  version: 1.0.0
paths:
  /v1/users:
    get:
      summary: List system users
      operationId: listUsers
      responses:
        '200':
          description: Successfully fetched users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
  responses:
    BadRequest:
      description: Invalid request payload

This production-grade spec uses clean plural collection endpoints (/v1/users), operationIds, explicit schemas, and reusable error components.

How APIForge checks this

  • Checks for version segment prefix (/v1)
  • Validates unique operationId declarations
  • Verifies error status code responses (400, 404, 500)
  • Confirms component $ref resolution
Share
X (opens in a new tab)LinkedIn (opens in a new tab)