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.

Generate API reference in new instance

Add the OpenAPI specification file (YAML or JSON) to the project.
In the Writerside tool window toolbar, click and select New Instance | 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 instance.

Generate API reference in existing instance

Add the OpenAPI specification file (YAML or JSON) to the project.
In the Table of Contents pane of the Writerside tool window, click 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 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"/>

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

{
  "message": "Document created"
}

{
  "message": "Bad Request"
}

Last modified: 11 November 2024