How do I create a public API docs site with code samples?

To create a public API docs site with code samples, you typically need 4 parts:

1. A source of truth for the API spec
2. A docs generator or site framework
3. Code sample generation or authoring
4. Deployment and versioning

Here’s a practical approach.

---

1) Start with an API specification

Use one of these as the canonical source:

• OpenAPI (recommended) for REST APIs
• AsyncAPI for event-driven/message APIs
• GraphQL schema for GraphQL APIs

For a public docs site, OpenAPI is the most common choice.

Example

Create an openapi.yaml or openapi.json file that includes:

• endpoints
• request/response schemas
• auth
• examples
• error responses

Good specs make docs generation much easier.

---

2) Choose a docs platform

Option A: Hosted API docs tools

Good if you want fast setup and minimal maintenance:

• Redoc
• Swagger UI
• Stoplight
• Fern
• Bump.sh
• ReadMe

These can render OpenAPI and often support:

• interactive “try it”
• auth
• examples
• versioning
• markdown pages

Option B: Build a custom docs site

Good if you want full control over branding and content.

Common stack:

• Next.js / Docusaurus / MkDocs / Astro
• embed OpenAPI-rendered docs with Redoc or Swagger UI
• write custom guides in Markdown/MDX

---

3) Add code samples

You have a few ways to do this.

A. Write samples manually

Add examples for each language in your docs pages:

• curl
• JavaScript
• Python
• Java
• Go
• C#

This is best when:

• the API is small
• you want polished examples
• you can keep them maintained

B. Generate samples from the OpenAPI spec

Some tools can generate snippets automatically:

• Redoc
• Swagger UI
• Postman
• Stoplight
• OpenAPI codegen tools

This is good for quick coverage, but auto-generated code snippets may be less polished.

C. Use a code sample generator

Many platforms let you define one example request and generate snippets in multiple languages.

For example, you can provide:

• sample request body
• sample headers
• example response

Then display code tabs for:

• cURL
• JavaScript fetch
• Python requests
• Node Axios

Best practice

Combine both:

• automated snippets for endpoint-level docs
• curated examples for important workflows

---

4) Structure the site

A good public API docs site usually has:

Core sections

• Getting Started
• Authentication
• Quickstart
• API Reference
• Errors
• Rate Limits
• Webhooks if applicable
• SDKs
• Changelog / Versioning
• FAQ / Support

API reference pages

For each endpoint:

• description
• auth requirements
• parameters
• request example
• response example
• code samples
• possible errors

---

5) Make the code samples useful

Good examples should be:

• copy-pasteable
• complete
• language-specific
• using realistic values
• aligned with the current API version
• showing auth clearly

Example: cURL

curl -X POST https://api.example.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com"
  }'

Example: JavaScript fetch

const response = await fetch("https://api.example.com/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Alice Johnson",
    email: "alice@example.com",
  }),
});

const data = await response.json();
console.log(data);

---

6) Keep examples synchronized

This is one of the biggest maintenance issues.

Ways to reduce drift:

• generate docs from the OpenAPI spec
• use example payloads in the spec itself
• store samples as testable snippets in your repo
• run docs checks in CI
• version docs alongside the API

If possible, automate:

• validation of OpenAPI
• snippet syntax checks
• sample request tests against a sandbox API

---

7) Publish and deploy

Typical deployment options:

• GitHub Pages
• Vercel
• Netlify
• Cloudflare Pages
• your own static hosting/CDN

If using a static docs site:

• build from Markdown/MDX + OpenAPI spec
• deploy on every merge to main
• use preview deployments for review

---

8) A simple recommended setup

If you want a straightforward, modern stack:

Fastest path

• Write an OpenAPI spec
• Use Redoc or Swagger UI for reference docs
• Build a Docusaurus or Next.js site for guides
• Add code samples manually for key workflows
• Host on Vercel or Netlify

More polished path

• OpenAPI spec
• Fern or ReadMe for docs and SDKs
• generated language snippets
• versioned docs
• automated publishing from CI

---

9) If you want the simplest possible path

If you already have OpenAPI, you can be up in minutes:

• Swagger UI: easy interactive reference
• Redoc: cleaner API docs presentation
• add Markdown pages for guides and code samples

---

10) Best practices checklist

• Use OpenAPI as the source of truth
• Include auth docs and examples
• Provide curl and at least 2–3 language samples
• Show request and response examples
• Document errors and rate limits
• Version the docs
• Add a sandbox environment
• Test code samples in CI if possible

---

If you want, I can also give you:

1. a recommended tech stack based on your language/framework, or
2. a step-by-step example for building a docs site with OpenAPI + Docusaurus/Next.js.