Before deploying APIs or publishing developer portals, use this checklist to ensure your OpenAPI specification meets modern engineering standards.
1. Specification & Syntax Structure
- Valid OpenAPI 3.0.x or 3.1.x root object fields (openapi, info, paths)
- Valid YAML / JSON formatting without syntax errors
- All internal and external $ref pointers resolve successfully
- Descriptive API title, version, and license information
2. Operations & Path Definitions
- Unique operationId attributes for SDK generator compatibility
- Explicit HTTP status code responses (200, 400, 401, 404, 500)
- Defined requestBody content types (application/json)
- Parameter location specifiers (in: query, path, header)
3. Security & Authentication Schemas
- Global securityRequirements array declared
- securitySchemes defined under components (Bearer, OAuth2, ApiKey)
- HTTPS scheme enforced for all server URLs