Generate API reference

Use the <api-doc> element to generate an API reference from a specification. You can generate the full API reference of all operations or a subset based on the specified tags.

Add the OpenAPI specification files (YAML or JSON) to the project.
Click in the table of contents and select API Reference.
In the Generate API Reference dialog, point to the location of the API specification file.
You can choose to generate XML or Markdown topics, create separate topics for objects and endpoints. If you do not select any options, the API reference will be generated in one topic.
Click OK and wait for Writerside to generate the new topics.

You can also use the <api-doc> element in any topic where you want to add a generated reference of the API specification. If necessary, add the tag attribute to generate a reference only for operations with a specific tag.

<api-doc openapi-path="path/to/spec.yaml"/>

<api-doc openapi-path="path/to/spec.yaml" tag="Pet"/>

The <api-doc> element has the following attributes:

openapi-path: Path to the OpenAPI specification file.
tag: Generate reference only for operations marked with this tag.

Writerside generates a separate chapter for each operation, uses the summary as the title, and adds all necessary details about the endpoint: URL, parameters, headers, requests with optional samples, and responses. Use the preview to see how it will render.

Here is an example of a generated OpenAPI reference with just one endpoint:

Create a new document

/documents

Request parameters

{
  "title": "Example Document",
  "content": "This is some example content for the document."
}

Responses

null

Last modified: 08 March 2024