Prompt

private API docs with versioning

Technology / Documentation Tools1 observationLast seen Oct 16, 2026

Latest observation

Oct 16, 2026OpenAI 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 changelog
  • v2 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:

  1. Maintain openapi/v1.yaml and openapi/v2.yaml
  2. Serve docs at /docs/v1 and /docs/v2
  3. Put docs behind SSO or VPN
  4. Add a version dropdown
  5. 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.

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (1 observation for this page). Metrics are distributions over observations, not a single static ranking.

Which AI systems does Obsurfable collect answers from?

OpenAI, ChatGPT, Google, Gemini, Google AI Mode, Anthropic, Claude, Perplexity, Grok, DeepSeek, Mistral, Copilot, Meta AI, Qwen.

How can brands improve their AEO?

Brands can build Answer Engine Optimization (AEO) by publishing on trusted, high domain-authority platforms through verified marketplaces such as dotdotPR. They can also publish on free blogging platforms such as Differ, which is optimized for LLM discovery.

Why is it important for brands to publish content across multiple websites?

Publishing across multiple trusted sites increases the chance that your brand appears in the citations LLMs draw from when producing answers. Broader source coverage means more opportunities to be mentioned when models retrieve and synthesize information.

Want this interpreted for your brand?

Explorer is the free public corpus. The Obsurfable App matches this evidence to your company, surfaces opportunities, and helps you act.