Prompt
private API docs with versioning
Latest observation
Oct 16, 2026
OpenAI APIWeb search: off
Here’s a practical way to structure private API docs with versioning.
Core approach
Keep the docs tied to the API version, not just the codebase. A common pattern is:
- One docs site
- Version selector in the UI
- Separate OpenAPI/Swagger files per version
- Authentication required to access the docs if the API is private
Recommended structure
URL structure
/docs→ default/latest docs/docs/v1/docs/v2
Spec files
/openapi/v1.yaml/openapi/v2.yaml
Access control
Use one of:
- SSO login
- OAuth2 / OIDC
- API key behind a portal
- Internal network/VPN only
- Basic auth for lightweight setups
Best practices
1. Version the API explicitly
Use one of these strategies:
- URL versioning:
/v1/users - Header versioning:
Accept: application/vnd.company.v1+json - Query versioning: less common, usually avoid
For private APIs, URL versioning is often easiest for docs and consumers.
2. Docs should match the version exactly
Each version should include:
- Endpoints
- Request/response schemas
- Auth requirements
- Error codes
- Deprecation notes
- Breaking changes between versions
3. Mark lifecycle status
For each version, label it:
- Current
- Deprecated
- Sunset
- Archived
4. Keep changelogs per version
Examples:
v1 changelogv2 release notes- migration guides from
v1 → v2
5. Automate doc generation
Generate docs from source of truth:
- OpenAPI/Swagger
- Postman collections
- API Blueprint
This reduces drift.
Example docs layout
docs/
index.md
v1/
overview.md
auth.md
endpoints/
users.md
orders.md
v2/
overview.md
auth.md
endpoints/
users.md
orders.md
openapi/
v1.yaml
v2.yaml
Suggested tooling
For hosted/private docs portals
- Redocly
- Swagger UI
- Stoplight
- ReadMe
- Slate for static docs
For access control
- API gateway auth
- Auth0 / Okta / Azure AD / Keycloak
- Reverse proxy with auth (Nginx, Cloudflare Access, Tailscale, etc.)
Minimal pattern to implement
If you want a straightforward setup:
- Maintain
openapi/v1.yamlandopenapi/v2.yaml - Serve docs at
/docs/v1and/docs/v2 - Put docs behind SSO or VPN
- Add a version dropdown
- Add a deprecation banner for old versions
Example deprecation notice
v1 is deprecated and will be removed on 2027-03-31. Please migrate to v2.
If you want, I can also give you:
- a sample folder structure
- a Swagger/OpenAPI versioned docs setup
- or a private docs portal architecture for your stack.