In short
An API without docs is a shop without a signboard. In this project you'll give an API you built a proper docs site that a stranger could use without messaging you even once.
A polished, interactive documentation site for an API you've built — practice for OpenAPI specs and making your work genuinely usable by other developers.
Think of it like this
A guidebook for visitors
A good city guidebook has tabs, clear sections, sample routes and tips for first-timers. Visitors don't call you for directions. Your docs site is that guidebook: a quick start, how auth works, every endpoint with examples, and the errors people will hit.
Watch it happen
Build plan
1/5Write or generate openapi.yaml for your API, with examples for each request and response.
The big ideas
What you need to know
A five-minute quick start
A new reader should make their first successful call within five minutes, with copy-paste-ready commands.
Auth explained first
Show exactly how to get a key or token and which header to send, with a working example.
Errors documented
List each error code, what causes it and how to fix it. This saves the most support messages.
Docs live with code
Keep the spec in the same repo and rebuild docs in CI, so they never fall behind.
See it in code
Walk through the code
1name: docs2on:3 push:4 branches: [main]5jobs:6 build:7 runs-on: ubuntu-latest8 steps:9 - uses: actions/checkout@v410 - run: npx @redocly/cli lint openapi.yaml11 - run: npx @redocly/cli build-docs openapi.yaml -o site/index.html12 - uses: actions/upload-pages-artifact@v313 with:14 path: site1/4The workflow runs on every push to main.
Pair this with a deploy job that uses actions/deploy-pages, and set Pages to deploy from GitHub Actions in the repo settings.
Save yourself the pain
Common mistakes
Oops
Only auto-generated reference pages, no guides at all.
Do this instead
Reference says what exists; guides say how to start. Add at least a quick start and an auth page.
Oops
Examples that don't actually work against the real API.
Do this instead
Test your examples, ideally by running them in CI with Newman or a script, before you publish.
Your mission
First milestone: live docs
Quick check
What's the main benefit of building docs from the OpenAPI spec in CI?
Go deeper
- 1Generate an OpenAPI spec covering every endpoint, with example requests/responses.
- 2Host interactive docs (Swagger UI or Redoc) so visitors can try requests live.
- 3Include authentication instructions and error-code references in the docs.
More projects at this stop
GraphQL API
Stuck on this topic? Ask an Insider
Get 1:1 guidance from people who've walked this exact path — on the InsideEdge app.
