# Generate single API endpoint reference Use the `` element to generate a reference for a single API endpoint and its HTTP method (operation). Procedure: 1. Put the OpenAPI specification files (YAML or JSON) anywhere in the project. 2. Add the `` 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. ```XML ``` If you want to add several endpoints from the same specification, wrap them inside the `` element. ```XML ``` 3. If necessary, add request and response samples manually. For details, see [Request samples](#providing-request-samples) and [Response samples](#providing-response-samples). The `` element has the following attributes: openapi-path : The path to the OpenAPI specification. Not necessary if the `` element is inside the `` element. endpoint : The name (path) of the endpoint. method : The HTTP method. Here is an example of a single endpoint reference: OpenAPI endpoint: POST /documents ## Request parameters **Request** Body Content type: application/json - **application/json** (Document, required) - **title** (string) - **content** (string) **JSON example** ```JSON { "title": "Example Document", "content": "This is some example content for the document." } ``` ## Responses **Response 201** Content type: application/json Document created successfully - **application/json** (null) **201** ```JSON { "message": "Document created" } ``` **Response 400** Content type: application/json Bad Request - **application/json** (null) **400** ```JSON { "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 `` element inside `` and use one or more `` 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: ```XML { "id": 123, "name": "John Doe", "email": "john.doe@example.com" } const data = { id: 123, name: "John Doe", email: "john.doe@example.com" }; ``` The `` 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](writerside-cfg.html)` 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 `` element inside ``. It has a required attribute `type` to specify the response code, such as `200`, `400`, or `default`. Use the `` element inside `` 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. ```XML { "id": 123, "name": "John Doe", "email": "john.doe@example.com" } { "error": "text" } ``` The `` 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](writerside-cfg.html)` 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: ```XML ```