OpenAPI Path Generator

An OpenAPI path definition describes a single HTTP endpoint in your API. It lives under the top-level 'paths' key in your openapi.yaml or openapi.json file and specifies the HTTP method (GET, POST, etc.), input parameters, request body schema, and all possible response codes. The OpenAPI 3.x specification is maintained by the OpenAPI Initiative and is the industry standard for describing REST APIs in a language-agnostic way.

OpenAPI 3.1 (released 2021) aligns fully with JSON Schema Draft 2020-12, removing several OpenAPI-specific keywords in favour of standard JSON Schema equivalents. Key changes: 'nullable' is replaced by adding 'null' to the 'type' array (e.g. type: [string, null]), 'exclusiveMinimum'/'exclusiveMaximum' are now numeric values, and 'discriminator' works with any schema combiner. Most tooling (Swagger UI, Redoc, code generators) supports both versions. The output from this tool is compatible with both 3.0 and 3.1.

The operationId is a unique string identifier for an operation across the entire API. It must be unique within the document. It is used by code generators (openapi-generator, swagger-codegen, Kiota) to name the generated client methods — so 'getUser' becomes client.getUser(). A missing or duplicate operationId breaks most code-gen tools. Best practice: use camelCase, follow the pattern verbResource (e.g. listUsers, createOrder, deleteComment).

Use 'in: path' for resource identifiers that are part of the URL structure, such as /users/{id} or /orders/{orderId}/items/{itemId}. Path parameters are always required. Use 'in: query' for filtering, sorting, pagination, and optional modifiers: /users?role=admin&page=2&limit=20. Use 'in: header' for technical metadata like API versions (X-API-Version), idempotency keys (Idempotency-Key), or correlation IDs. Never put sensitive data like API keys in path or query params — use 'in: header' or a security scheme.

OpenAPI supports $ref pointers to avoid repeating schemas. Define shared schemas under components/schemas in your openapi.yaml: components: schemas: User: type: object properties: id: { type: string } Then reference them anywhere: $ref: '#/components/schemas/User'. This tool generates inline schemas for quick starts — for production APIs, extract schemas to components/schemas and replace inline definitions with $refs.

Several free tools can validate your OpenAPI YAML or JSON: (1) Swagger Editor at editor.swagger.io — paste your document for instant feedback. (2) Redocly CLI: npm install -g @redocly/cli && redocly lint openapi.yaml — strict linting with opinionated rules. (3) Spectral by Stoplight: npm install -g @stoplight/spectral-cli — highly configurable rule sets including custom rules. (4) openapi-generator validate — validates before generating client SDKs. For CI/CD, Redocly and Spectral both support config files and exit codes for pipeline gates.