What You Will Build
By the end of this tutorial, you will have a fully branded, interactive API documentation site with:
- Auto-generated endpoint reference from your OpenAPI spec
- An interactive API playground for testing calls
- AI-powered chatbot for developer questions
- Custom branding (colors, logo, fonts)
- A shareable public URL
Total time: about 3 minutes if you already have an OpenAPI spec file.
Prerequisites
- An OpenAPI 3.0 or 3.1 spec file (JSON or YAML)
- A free Specway account at specway.dev
If you do not have a spec file handy, you can use one of Specway's built-in sample specs (Petstore, Stripe, or GitHub) to follow along.
Step 1: Create Your Documentation Site
After signing in to Specway, you will land on the dashboard. Click "New Doc Site" in the top right corner.
You will see a modal with two options:
- Import OpenAPI Spec — Upload a file or paste a URL
- Start from Sample — Use a pre-loaded spec to explore
Choose Import OpenAPI Spec and either drag your spec file into the upload area or paste a URL to a hosted spec.
Specway validates your spec on upload. If there are any issues, you will see specific warnings with line numbers. Most valid OpenAPI 3.0 and 3.1 specs import without issues.
The import typically takes 2-5 seconds for specs with up to 200 endpoints.
Step 2: Explore Your Generated Docs
Once the import completes, Specway redirects you to your new documentation site. You will see:
- Left sidebar — Auto-generated navigation organized by your spec's tags. Every endpoint is listed with its HTTP method badge (GET, POST, PUT, DELETE).
- Center panel — Endpoint description, parameters, request body schema, and response examples — all pulled directly from your spec.
- Right panel — Interactive playground where developers can make real API calls.
Take a moment to click through a few endpoints. Notice that:
- Path parameters, query parameters, and headers are all documented automatically
- Request and response schemas show the full type structure with descriptions
- Example values from your spec are pre-filled in the playground
Quick Checkpoint
If your endpoints look correct and the navigation matches your spec's tag structure, you are on track. If something looks off, it usually means your spec has missing tags or descriptions — Specway renders exactly what the spec contains.
Step 3: Customize Your Branding
Click the Settings icon (gear) in the top navigation bar to open the site settings panel.
Logo
Upload your company logo. Specway accepts PNG, SVG, or JPG. The logo appears in the top-left corner of your doc site and in the browser tab favicon.
Colors
Set your primary brand color using the color picker or by entering a hex code. This color is applied to:
- Navigation highlights
- HTTP method badges
- Links and interactive elements
- The AI chatbot interface
Fonts
Choose from a curated list of developer-friendly fonts (Inter, JetBrains Mono, Fira Code, etc.) or enter a custom Google Fonts URL.
Custom Domain
On paid plans, you can point a custom domain (e.g., docs.yourcompany.com) to your Specway site. Add a CNAME record pointing to docs.specway.dev and enter your domain in the settings. SSL is provisioned automatically.
Branding changes preview in real time — no need to save and reload.
Step 4: Set Up the API Playground
The interactive playground works out of the box for public APIs. For authenticated APIs, the playground sends an optional Bearer token in the Authorization header. Developers paste their token once and can save it in their browser for later visits.
Your docs also include an Authentication page. Pick the auth type you use (API Key, Bearer Token, or OAuth 2.0) and document how developers get credentials, the header to send, and any scopes. The playground itself does not run an OAuth flow or send custom API-key headers, so explain those steps on that page.
Test It
Enter a test token in the playground and try making a call to one of your endpoints. You should see the actual response from your API, along with generated code snippets in cURL, Node, Python, Ruby and PHP.
Step 5: Enable the AI Chatbot
Navigate to Settings > AI Chatbot. Toggle it on.
The AI chatbot is automatically trained on your OpenAPI spec — no additional configuration needed. It understands:
- Every endpoint, parameter, and response schema
- Authentication requirements
- Error codes and their meanings
- Relationships between endpoints
Try asking it a question like "How do I create a new user?" or "What authentication method does this API use?" It will respond with the relevant endpoint, parameters, and a code example.
Step 6: Publish
Your doc site is live as soon as you import the spec. By default, it is accessible at:
https://your-site-name.specway.dev
You can change the subdomain in Settings, or connect a custom domain as described in Step 3.
Share the URL with your team or your API consumers. The site is fully responsive and works on desktop, tablet, and mobile.
Keeping Docs Up to Date
The most important thing after initial setup is keeping your docs in sync with your API. Specway offers two approaches:
Manual Re-import
Upload an updated spec file at any time. Specway diffs the changes and updates the docs without losing your branding or settings.
Re-Sync From Your Spec URL
If you imported from a URL, Specway re-checks that URL when you open the API in your dashboard. Click sync to see which endpoints were added, modified or removed, then apply the changes you want. You can also turn on an email notification for when a check finds changes.
Next Steps
Now that your docs are live, consider:
- Adding guides — Write supplementary guides (quick start, authentication walkthrough) in the Specway editor
- Monitoring analytics — Check which pages get the most views
- Collecting feedback — Enable the feedback widget so developers can flag issues directly in the docs
Conclusion
You now have a fully functional, branded API documentation site with interactive playground, AI chatbot, and one-click re-sync from your spec. The entire setup took less than three minutes.
The ongoing work is minimal: keep your OpenAPI spec up to date and re-sync when it changes.