APIForge
OPENAPI

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.

Problem Statement

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

❌ Anti-Pattern / Bad Implementation

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

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

✓ Refactored / Recommended Implementation

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

good-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

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

Test your own OpenAPI specification against these checks

Paste any OpenAPI specification URL or YAML file into APIForge for instant 0-100 quality scoring, schema linting, and zero-CORS proxy testing.

Run API Score Check →
Share:𝕏 Postin Share