If your product has an API, Cornerspot can write the documentation for you. The Import OpenAPI Specification wizard turns an OpenAPI 3.x definition into a complete, publishable API reference — one category for the reference, one polished article per resource group, each with endpoint details, parameter tables, and code samples. This guide walks through the whole flow, including the Use AI to select icons helper and editing code samples afterwards.
What the importer creates
- One top-level category named after your API, holding the whole reference.
- One section (sub-category) and one article per resource group — your spec's tags.
- Per-endpoint documentation in every article: the method and path, a description, parameter and response tables, and an optional code samples block.
- Drafts, not live pages — nothing is published until you publish your knowledge base, so you can review everything first.
How to import your OpenAPI specification
1. Open the Import menu
Go to Knowledge Base → Articles (at /dashboard/settings/help-center/articles) and click Import in the header. Choose OpenAPI Specification.
2. Choose your source
You can provide your definition two ways:
- Upload a file — drag and drop a
.yaml,.yml, or.jsondefinition (up to 10 MB). - Fetch from a URL — paste a direct link to the definition. You can even paste a documentation page (Swagger UI, Redoc, and similar): Cornerspot reads the page and discovers the spec URL for you.
3. Review the syntax check
Your spec is parsed and validated in seconds (no AI is involved in analysis). The Syntax Review groups anything it found by kind. Warnings — like a resource group or endpoint without a description — never block the import; they just mean the generated docs are a little thinner in those spots. Only true blockers (an unsupported version, an unreadable file) stop you, with clear instructions to fix and re-upload.
4. Name the reference and its sections
Next you shape the structure: the top-level category and one section per resource group, each with an editable name and icon. Rename anything — slugs update as you type.
Rather than picking icons for dozens of sections by hand, click Use AI to select icons. Cornerspot's AI reads each section's name and picks the most fitting icon from the icon library, applying them all at once — people for Accounts, a clock for Activities, a message bubble for Chat. It runs in the background and uses your team's included AI credits.
These icons aren't just decoration: they carry through to your knowledge base's navigation menus and category views, helping readers see what each section covers at a glance. And if a pick isn't quite right, just click the icon to open the picker and choose your own (or click Reset names to undo everything, names and icons alike).
5. Choose a code samples strategy
Every endpoint section can include a tabbed code samples block. You have three options:
- Use samples from the specification — if your spec ships code samples as
x-codeSamples(orx-code-samples) vendor extensions, Cornerspot uses your curated examples exactly as written. The step shows how many endpoints include them; endpoints without samples get none (you can add them later in the editor). - Generate samples automatically — runnable request examples built from each endpoint's definition, in your choice of twelve languages (cURL, JavaScript, Node.js, Python, Ruby, PHP, Go, Java, C#, Kotlin, Swift, and Rust). Generation is deterministic — built from the spec, not written by AI — and uses each language's standard capabilities with no vendor SDKs.
- No code samples — skip them for now and add samples later from the article editor.
6. Generate the documentation
Click Generate and Cornerspot writes an article for every resource group, one at a time, with live progress. This runs in the background — it's safe to leave the page and come back; the run picks up right where it was.
7. Review the result
When it finishes you'll see a summary of what was created. View articles takes you to the Articles list already filtered to your new reference, and Publish your knowledge base is one click away when you're ready to go live.
Working with code samples in the editor
Open any generated article and switch the editor to Split to see your content and a live reader preview side by side — including the code samples block, rendered exactly as readers will see it, with a tab per language.
Click a code samples block to open the samples editor. From there you can:
- Edit any sample — each language is a tab backed by a full code editor.
- Add a language — pick from the twelve-language catalog, or choose Custom language… to add your own tab (say, for your SDK).
- Remove a language — click the ✕ on its tab twice to confirm.
Click Save in the samples editor, then Save the article. You can also insert a brand-new code samples block anywhere in any article from the editor toolbar.
Your reference, live on your docs site
Once you publish your knowledge base, the reference is part of your hosted documentation site — with reader-friendly navigation built from your sections and icons, interactive code sample tabs, and a visitor-facing dark mode. Here's the Contacts article we just edited, live and in context, Ruby tab included:
Shipping code samples inside your spec
To have the importer use your own curated examples, add an x-codeSamples (or x-code-samples) array to any operation in your OpenAPI definition. Each entry needs a lang and a source, with an optional label for the tab:
paths:
/contacts:
get:
summary: List contacts
x-codeSamples:
- lang: curl
source: |
curl -s "https://api.example.com/contacts" \
-H "Authorization: Bearer $API_KEY"
- lang: python
source: |
import requests
requests.get("https://api.example.com/contacts")Languages that match the catalog (like curl, javascript, or python) get their standard tab labels automatically; anything else passes through as a custom tab.
Re-importing when your API changes
Run the import again any time your spec changes — it's safe by design. Articles you haven't touched are refreshed with newly generated content, while anything you've hand-edited is kept by default (you decide per article, and overwriting an edited article always asks for confirmation). Deleted articles are recreated, and your category names, icons, and ordering are preserved.
Tips for a polished API reference
- Add descriptions to your spec's tags and operations — the Syntax Review shows exactly where they're missing, and richer specs make richer docs.
- Ship
x-codeSamplesfor your most important endpoints and let the generator cover the rest on a later import. - Generated articles are drafts — review them in Split view, then publish your knowledge base when you're happy.