Writerside Help

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.

  1. Put the OpenAPI specification files (YAML or JSON) anywhere in the project.

  2. Add the <api-doc> element anywhere in a topic where you want to generate the API reference.

  3. 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

POST method/documents

Request parameters

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

Responses

Last modified: 12 October 2023