TemplateFREE⏱️ 90-120 minutes
OpenAPI Specification Template for PMs
A structured template for writing OpenAPI 3.1 specifications covering paths, schemas, authentication, error responses, and server configuration.
Updated 2026-03-05
OpenAPI Specification
| # | Item | Category | Priority | Owner | Status | Notes | |
|---|---|---|---|---|---|---|---|
| 1 | |||||||
| 2 | |||||||
| 3 | |||||||
| 4 | |||||||
| 5 |
#1
#2
#3
#4
#5
Edit the values above to try it with your own data. Your changes are saved locally.
Get this template
Choose your preferred format. Google Sheets and Notion are free, no account needed.
Frequently Asked Questions
When should I write the OpenAPI spec: before or after implementation?+
Write it before implementation. The spec serves as a design document that frontend engineers, partner teams, and QA can review and build against in parallel. If you write it after, you are documenting what the code happens to do rather than what it should do. The spec-first approach also enables code generation for server stubs and client SDKs, which accelerates both provider and consumer development.
Should I use YAML or JSON for the OpenAPI spec?+
YAML is more readable for humans and is the convention for hand-written specs. JSON is better for machine-generated specs and for embedding in code. Most teams write in YAML and let tools convert to JSON when needed. Whichever format you choose, commit the spec to version control alongside the source code and treat changes to it with the same rigor as code changes.
How do I keep the spec in sync with the implementation?+
Use contract testing. Tools like Prism (mock server from OpenAPI spec), Dredd (test runner that validates implementation against spec), and Schemathesis (property-based testing from OpenAPI) catch drift automatically. Run these tests in CI so that any divergence between the spec and the implementation blocks deployment. For more on contract testing, see the [API Testing Strategy Template](/templates/api-testing-template).
Should I use $ref for everything or inline some schemas?+
Use `$ref` for any schema referenced in more than one place. Inline schemas only for one-off request parameters that are unique to a single endpoint. Over-inlining creates duplicate definitions that drift out of sync. Over-referencing makes the spec hard to read because readers must jump between sections. The balance point: define all request/response body schemas and all shared types in `components/schemas`, and inline only simple query parameter schemas.
How do I handle API versioning in OpenAPI?+
Include the version in the `info.version` field and in the server URL path (`/v1/`). When you release a breaking change, create a new spec file for v2 (`openapi-v2.yaml`) rather than modifying the v1 spec. Keep the v1 spec frozen and maintained alongside the v1 implementation until that version is sunset. This gives consumers a stable reference for each version. ---
Explore More Templates
Browse our full library of PM templates, or generate a custom version with AI.