How do I create a public docs site from an API spec?

You can create a public docs site from an API spec by using a docs generator or API documentation platform that reads your spec and publishes a website.

Typical workflow

1. Start with an API spec

   • Usually OpenAPI (Swagger) for REST APIs
   • Sometimes AsyncAPI for event-driven APIs
   • Or GraphQL schema for GraphQL APIs

2. Choose a docs tool Common options:

   • Redoc / Redocly — attractive OpenAPI docs
   • Swagger UI — interactive API reference
   • Stoplight — API design + docs hosting
   • ReadMe — hosted docs with portals, guides, and reference
   • Docusaurus / MkDocs / Mintlify — custom docs site with API reference embedded

3. Generate or connect the site

   • Upload or link your spec file
   • The tool renders endpoints, schemas, auth, examples, and models
   • Add guides, getting started pages, and changelogs if needed

4. Publish publicly

   • Host on the provider’s platform, or
   • Build statically and deploy to GitHub Pages, Netlify, Vercel, Cloudflare Pages, etc.

---

Fastest options

Option A: Hosted docs platform

Best if you want the least setup.

Examples:

• ReadMe
• Stoplight
• SwaggerHub
• Mintlify

Typical steps:

• Import OpenAPI spec
• Customize branding and navigation
• Set the site to public
• Share the generated docs URL

Option B: Static site + embedded API reference

Best if you want full control.

Typical stack:

• Docusaurus or MkDocs
• Redoc or Swagger UI for API reference
• Deploy to a static host

Example:

• Put openapi.yaml in your repo
• Add a docs page that renders Redoc
• Deploy the built site to GitHub Pages/Netlify

---

Minimal example with Redoc

If you have an openapi.yaml, you can create a simple public page like this:

<!doctype html>
<html>
  <head>
    <title>API Docs</title>
    <meta charset="utf-8" />
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </head>
  <body>
    <redoc spec-url="https://yourdomain.com/openapi.yaml"></redoc>
  </body>
</html>

Then host:

• the HTML page
• the openapi.yaml file

---

Things to include in good public docs

• Overview / getting started
• Authentication
• Base URL
• Endpoints with examples
• Error codes
• Rate limits
• Webhooks or events
• SDK links if available
• Changelog / versioning

---

Important tips

• Make sure your spec is clean and complete
• Add examples to requests/responses
• Use clear security schemes for auth
• Validate the spec before publishing
• Keep docs updated automatically from source control

If you tell me what kind of spec you have (OpenAPI, Swagger, GraphQL, AsyncAPI) and where you want to host it, I can recommend the simplest exact setup.