OPENAPI

Bad OpenAPI Anti-Patterns & Refactoring Guide

Analyze common OpenAPI specification anti-patterns and learn how to refactor them into clean, standardized API contracts.

Problem Statement

Bad OpenAPI specifications contain broken references, duplicate operation IDs, verbs in URL paths, and GET requests with payload bodies.

❌ Anti-Pattern / Bad Implementation

Anti-pattern: Verbs in URL path (/createUser), GET method with request body, missing error responses.

bad-pattern.yaml

paths:
  /createUser:
    post:
      summary: create user
  /getUserDetails:
    get:
      requestBody:
        content:
          application/json:
            schema:
              type: object

✓ Refactored / Recommended Implementation

Refactored: RESTful resource URLs (/v1/users), standard HTTP POST for creation, and GET with query parameters.

good-pattern.yaml

paths:
  /v1/users:
    post:
      summary: Create a new user
      operationId: createUser
      responses:
        '201':
          description: Created
  /v1/users/{id}:
    get:
      summary: Get user details by ID
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

How APIForge Checks This

Detects GET requests containing request bodies
Flags verb segments in path names
Scores naming and path depth consistency

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:𝕏 Post in Share