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, you need to configure the authentication method:

1. In Settings, navigate to Authentication
2. Select your auth type: API Key, Bearer Token, or OAuth 2.0
3. Configure the header name and format

For API Key authentication:

• Set the header name (e.g., X-API-Key or Authorization)
• Set the value prefix if needed (e.g., Bearer)

For OAuth 2.0:

• Enter the authorization URL, token URL, and available scopes
• Specway handles the OAuth flow when developers click "Authorize"

Once configured, developers visiting your docs can enter their own credentials and make authenticated API calls directly from the playground.

Test It

Enter a test API key in the playground and try making a call to one of your endpoints. You should see the actual response from your API rendered in the right panel, along with generated code snippets in JavaScript, Python, Go, and cURL.

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.

Auto-Sync via CI/CD

Add Specway's CLI to your deployment pipeline:

npx specway-cli push --api-key YOUR_KEY --spec ./openapi.yaml

This command uploads your latest spec to Specway on every deploy. Your docs are always current, with zero manual effort.

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 endpoints get the most views and playground interactions
• 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 automatic spec sync. The entire setup took less than three minutes.

The ongoing work is minimal: keep your OpenAPI spec up to date, and Specway handles the rest.