Generate single API endpoint reference

Use the <api-endpoint> element to generate a reference for a single API endpoint and its HTTP method (operation).

Put the OpenAPI specification files (YAML or JSON) anywhere in the project.
Add the <api-endpoint> element anywhere in a topic where you want to generate the API reference for an endpoint. Specify the path to the specification, the endpoint name and HTTP method.
<api-endpoint openapi-path="path/to/spec.yaml" endpoint="/users" method="GET"/>
If you want to add several endpoints from the same specification, wrap them inside the <api-doc> element.
<api-doc openapi-path="path/to/spec.yaml"> <api-endpoint endpoint="/users" method="GET"/> <api-endpoint endpoint="/users" method="POST"/> </api-doc>
If necessary, add request and response samples manually. For details, see Request samples and Response samples.

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

openapi-path: The path to the OpenAPI specification. Not necessary if the <api-endpoint> element is inside the <api-doc> element.
endpoint: The name (path) of the endpoint.
method: The HTTP method.

Here is an example of a single endpoint reference:

/documents

Request parameters

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

Responses

{
  "message": "Document created"
}

{
  "message": "Bad Request"
}

Request samples

Clear and illustrative code samples help developers understand the expected input and output of an API endpoint.

By default, Writerside generates request samples only for JSON. To override the generated samples, add the <request> element inside <api-endpoint> and use one or more <sample> elements to illustrate various request examples, helping developers see how to format their requests. For example, here is how you can provide samples for requests in JSON and JavaScript:

            <api-endpoint endpoint="/users" method="POST">
                <request>
                    <sample lang="JSON" title="Payload">
                    {
                        "id": 123,
                        "name": "John Doe",
                        "email": "john.doe@example.com"
                    }
                    </sample>
                    <sample lang="javascript" title="JavaScript">
                    const data = {
                        id: 123,
                        name: "John Doe",
                        email: "john.doe@example.com"
                    };
                    </sample>
                </request>
            </api-endpoint>
       

The <sample> element for requests has the following attributes:

lang

Language for code highlighting.

title

Title of the tab with the example. By default, it depends on the specified language: JSON example.

src

Name of the file with the code snippet.

The source file must be located under the directory you've specified in the snippets attribute of the writerside.cfg file.

include-lines

Range or comma-separated list of lines that you want to include.

Response samples

To provide custom samples for API responses, use the <response> element inside <api-endpoint>. It has a required attribute type to specify the response code, such as 200, 400, or default.

Use the <sample> element inside <response> to provide an example of the response. For example, the following API endpoint reference will have two custom response examples: one for a successful response with code 200 and one for an error response with code 400.

            <api-endpoint endpoint="/users/{id}" method="GET">
                <response type="200">
                    <sample>
                        {
                            "id": 123,
                            "name": "John Doe",
                            "email": "john.doe@example.com"
                        }
                    </sample>
                    </response>
                <response type="400">
                    <sample>
                        {
                            "error": "text"
                        }
                    </sample>
                </response>
            </api-endpoint>
        

The <sample> element for responses has the following attributes:

src

Name of the file with the code snippet.

The source file must be located under the directory you've specified in the snippets attribute of the writerside.cfg file.

include-lines

Range or comma-separated list of lines that you want to include.

You can also provide request and response samples from a file and define specific lines to include in the example:

            <response>
                <sample src="example.json" include-lines="5-10"></sample>
            </response>
        

Last modified: 13 October 2023