If your API has an OpenAPI file, PinkDocs can write your API reference for you. Upload the file and you get one article per endpoint, built with the API blocks: the method and path, every parameter, request examples in cURL, JavaScript, Python and PHP, and example responses for each status code.
What is an OpenAPI file?
OpenAPI (formerly called Swagger) is the standard way to describe a REST API in one file: its endpoints, the parameters each one takes, how to authenticate and what it returns. It's written in JSON or YAML and is usually named openapi.json, openapi.yaml or swagger.json.
Most API frameworks can create one for you (FastAPI, NestJS, Laravel with Scribe or L5-Swagger, Spring, ASP.NET, Rails with rswag…), and tools like Postman, Stoplight and SwaggerHub can export one. If your API has a page at an address like /docs, /swagger or /openapi.json, you probably already have one.
PinkDocs reads OpenAPI 3.0 and 3.1, and the common parts of Swagger 2.0, as .json, .yaml or .yml, up to 8 MB.
Import your file
Open the importer
Go to PinkDocs → Tools → Import OpenAPI.
Choose the file
Drop the file onto the box or click it to choose one. If the file is online, paste its address (for example https://api.example.com/openapi.json) and click Load instead.
PinkDocs reads the file and lists every endpoint it found, grouped by tag, with the API's name, version and server.
Pick where the articles go
- Knowledge base: the knowledge base to add the articles to.
- Categories: how to group them (see Categories below). By default you get a new category named after your API, with one sub-category per tag.
- Save new articles as: Drafts lets you review them before readers see them. Choose Published to make them live straight away.
Choose the endpoints
All endpoints are ticked. Untick the ones you don't want to document (for example internal or admin endpoints), or type in the Filter box to find them quickly. Each endpoint shows New if it will create an article, or Update if an earlier import already created one.
Import
Click Import. A progress bar shows how far it is; large files are imported in small batches so nothing times out. When it's done you get a list of the articles with Edit and View links.
What each part of your file becomes
| In your OpenAPI file | In the article |
|---|---|
summary (or operationId) | The article title. |
description | The introduction at the top (Markdown is kept). |
Method and path, servers | The API Endpoint block, with your server as the base URL. |
deprecated: true | A Deprecated label on the endpoint and in the parameters. |
security and securitySchemes | An Authentication section: a bearer token, an API key header or query parameter, or basic auth. |
parameters | Path parameters, Query parameters, Headers and Cookies sections, with type, required, default and description. |
requestBody | A Body section. Nested fields are listed with dots, like customer.email and items[].sku. |
enum | One of: … added to the description. |
example, examples, default | Used in the request and response examples. Without them, PinkDocs makes realistic values up from the schema (dates, emails, IDs…). |
x-codeSamples | Used as the request examples, exactly as written, instead of the generated ones. |
responses | The API Response Examples block: one tab per status code with its description. |
tags | Categories (the first tag of each endpoint). |
$ref references, allOf and the first option of oneOf and anyOf are resolved for you.
Categories
Choose how the articles are grouped in the Categories list:
| Option | Result |
|---|---|
| A new category for the API, with one sub-category per tag | Museum API → Events, Tickets… The default. |
| One top-level category per tag | Events, Tickets… next to your other categories. |
| One sub-category per tag, inside an existing category | For example inside an API reference category you already have. |
| Everything in one new category | One category, no sub-categories. |
| Everything in an existing category | Adds all articles to a category you choose. |
Endpoints without a tag go into an Endpoints category.
Keep your docs in sync
When your API changes, import the new version of the file the same way. PinkDocs recognises the articles it created before (by the API's name and each endpoint's method and path):
- Existing endpoints are updated. Only their API blocks (endpoint, parameters, request and response examples) are replaced.
- Your own changes stay. Titles you renamed, text you added before or after the API blocks, images, alerts, categories and tags are kept.
- New endpoints get new articles.
- Removed endpoints are left alone. Delete or unpublish their articles yourself if the endpoint is gone.
Example file
This small OpenAPI file creates one article, Create a ticket, in a Tickets category. Save it as openapi.yaml and import it to try the importer:
You can see the kind of article this produces in Sample: Create a ticket.
Use your own code samples
By default PinkDocs writes the request examples in cURL, JavaScript, Python and PHP. To show your SDKs or other languages instead, add x-codeSamples to an operation (the same extension Redoc uses). Each sample becomes a tab:
Tips for a better result
- Give every operation a
summary. It becomes the article title and the sidebar label, so keep it short and start with a verb: Create a ticket, List tickets. - Write a
descriptionfor operations that need explaining. It becomes the article's introduction. - Add
examplevalues to your schemas and responses. Real-looking examples (jane@example.com,tkt_8f2a91) help readers far more than generated ones. - Describe every parameter and field. Empty descriptions show as a name and type only.
- Use tags to group endpoints by resource (Tickets, Customers, Webhooks). Each tag becomes a category.
- Keep
$refs inside the file. References to other files or URLs aren't followed; bundle the file first (for example withredocly bundleorswagger-cli bundle).
Frequently asked questions
Yes. Paste the address of the JSON or YAML file and click Load. The address has to be publicly reachable from your WordPress site.
Only edits inside the API blocks. Your titles, introductions, extra text, categories and tags are kept. See Keep your docs in sync.
No. It only reads the file. Requests in the examples are never sent.
Files can be up to 8 MB, and up to 500 endpoints are imported at a time. Split very large APIs into several files, for example one per tag.
Yes. Each API is recognised by its title (info.title), so give them different titles and import them into different categories or knowledge bases.
If you've connected an AI tool over MCP, you can paste parts of your OpenAPI file and ask it to write the endpoint pages. It uses the same API blocks. For whole files, the importer is faster and keeps your docs in sync.