OpenAPI Snippet Generator

OpenAPI 3.0 is the industry-standard specification for describing HTTP APIs. It defines endpoints, request/response schemas, authentication, and more in a machine-readable YAML or JSON format. Tools like Swagger UI, Postman, and code generators consume OpenAPI specs to create documentation, client SDKs, and server stubs.

Path parameters are part of the URL path (e.g., /users/{id}) and are required. Query parameters come after ? in the URL (e.g., /users?page=2&limit=10) and are typically optional filters or pagination controls. Both are described in the 'parameters' section of an OpenAPI operation.

Use the 'requestBody' field with a 'content' map. For JSON: content: application/json: schema: {type: object, ...}. Define required vs optional fields with the 'required' array at the object level. Use $ref to reference shared schemas in the components/schemas section.

Document all expected HTTP status codes: 200 (success), 201 (created), 204 (no content), 400 (bad request/validation), 401 (unauthorized), 403 (forbidden), 404 (not found), 409 (conflict), 422 (unprocessable entity), 500 (server error). Include at least success and error responses.

$ref allows you to reference shared schemas defined in components/schemas instead of repeating them. This keeps your spec DRY and consistent. For example, an 'Error' schema used in all 4xx responses should be defined once in components and referenced with $ref: '#/components/schemas/Error'.