Writerside Help

Showcase API entities

API documentation is not only about describing operations, it is also about showcasing the entities your API works with. Entities are the building blocks of your API, and they represent the data structures which communicate and interact within the API. Documenting these entities and their interactions will help users understand the functionality and potential of your API.

Use the <api-schema> element to generate a reference of API entities. Specify the path to the API specification using the openapi-path attribute and the name of the data object using the name attribute.

<api-schema openapi-path="path/to/spec.json" name="EntityName"/>

By default, Writerside renders entity descriptions from all levels on one page. If you want to generate separate pages for entity objects and link to them, specify the nesting level using the depth attribute.

For example, depth="1" will generate separate pages for all entity objects and add links to those pages, while depth="3" will render descriptions of entities up to level 2 on the same page and add links to separate pages starting from entities on level 3.

<api-schema openapi-path="path/to/spec.json" name="EntityName" depth="3"/>

If you want to add links for all existing schema entity pages, use the display-links-if-available attribute.

Here is an example of a generated OpenAPI reference for a schema object called Document:


Last modified: 18 July 2024