Generate API reference
Last modified: 11 November 2024Use 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.
note
If there is no summary for an operation, Writerside will generate a chapter without a title and display a warning in the preview.
Here is an example of a generated OpenAPI reference with just one endpoint:
Create a new document
Request parameters
Body
{
"title": "Example Document",
"content": "This is some example content for the document."
}
Responses
{
"message": "Document created"
}
{
"message": "Bad Request"
}
Thanks for your feedback!