How do I support both public docs and internal docs from the same API spec?

A good way to support both public docs and internal docs from the same API spec is to treat the spec as the single source of truth, then generate different documentation views from it.

Common patterns

1. One spec, multiple doc outputs

Keep one OpenAPI/Swagger spec and use:

• tags
• visibility flags
• extensions/metadata
• separate doc generators or filters

For example:

• x-public: true
• x-internal: true
• x-audience: internal

Then your doc pipeline can:

• publish only public endpoints to the external docs site
• publish everything to the internal portal

2. Separate sections by audience

Organize endpoints and schemas so they can be filtered cleanly:

• public endpoints
• internal/admin endpoints
• beta/partner endpoints

Use consistent tags like:

• public
• internal
• admin

This makes it easy to hide or show groups.

3. Use security and environment-aware docs

Sometimes the same operation is visible to both audiences, but with different details:

• public docs show normal usage
• internal docs show implementation notes, debug fields, edge cases, or support guidance

You can keep those in:

• descriptions
• vendor extensions
• separate markdown linked from the spec

4. Hide internal details in the public spec

Be careful not to leak:

• internal hostnames
• private headers
• internal error codes
• staff-only fields
• rollout or migration notes

If you need to expose them internally, keep them in:

• x-internal-* fields
• internal-only markdown
• an internal doc overlay

5. Use overlays or post-processing

If your tooling supports it, create:

• a base OpenAPI spec
• a public overlay that removes internal paths/fields
• an internal overlay that adds extra descriptions/examples

This keeps maintenance low while allowing tailored docs.

Practical implementation options

Option A: Filter by tag

• Mark internal endpoints with internal
• Generate public docs by excluding that tag
• Generate internal docs with all tags included

Option B: Vendor extensions

Example:

paths:
  /users:
    get:
      x-audience: public
  /admin/users:
    get:
      x-audience: internal

Then filter docs based on x-audience.

Option C: Separate doc portals, same spec

Use one spec in source control, then:

• public docs site runs a filtered build
• internal docs site runs an unfiltered or enriched build

Best practice

If the distinction is important, explicitly model it in the spec rather than relying on naming conventions alone. That makes the setup easier to automate and less error-prone.

Recommendation

For most teams:

1. keep one OpenAPI spec
2. add audience metadata like x-audience
3. generate two doc outputs via filtering
4. avoid putting internal-only details in public descriptions

If you want, I can show you a concrete example in OpenAPI YAML and how to filter it into public vs internal docs.