API Pages

API pages enable you to create interactive playgrounds that enhance the developer experience. Developers can send requests and receive responses directly on each endpoint page, streamlining the integration process.

WriteDocs uses OpenAPI Specification (OAS) files to generate endpoint pages, thus ensure you have a valid OpenAPI document in JSON or YAML format that adheres to the OpenAPI 3.0+ specification.

Generating Endpoint Pages

To generate API endpoint pages in the API reference tab, you need to follow just a few steps:

Step 1. Add the OAS file

Add the OAS file to the openAPI folder in your documentation repository on GitHub.

Improving Endpoint Pages

To enhance the visual appeal and user experience of your endpoint pages, you can incorporate any WriteDocs components into the endpoint description within your OpenAPI specification.

Step 2. Link the OAS file to the apiFiles of your config.json

Specify the path to the OpenAPI file in the apiFiles attribute in the config.json file of your documentation repo, such as "apiFiles": ["example.yml"]. You can add multiple OAS files as needed.

Step 3. Use the WriteDocs CLI

WriteDocs CLI can automatically generate the endpoint markdown pages for you. To generate it, you need to follow the steps below:

1. Install WriteDocs CLI globally with npm i -g writedocs.
2. Navigate to your projects root directory in your terminal.
3. Execute the writedocs api command line to generate the pages.

Your generated pages can be found at the docs/reference folder.

Step 3. Reference the endpoints in the sidebar of your config.json

Define the paths to each endpoint in the sidebar object of the config.json file following the standard of the example below:

Template

...
  {
    "sidebarRef": "apiReference",
    "categories": [
      {
        "categoryName": "Example",
        "pages": [
        "reference/[OAS-file-name]/[endpoint-operation-id]"
        ]
      }
    ]
  }
...

Example

...
{
  "sidebarRef": "apiReference",
  "categories": [
    {
      "categoryName": "Example",
      "pages": [
      "reference/payments-api/create-payment",
      "reference/payments-api/get-payment"

      ]
    }
  ]
}
...

• [OAS-file-name]: The name of the OAS file contained in the reference folder.
• [endpoint-operation-id]: In the OAS file, each endpoint must have an operationId. This attribute will be used as the final path of the endpoint slug added to the apiReference array. The following code block presents where this parameter is usually locate inside the OAS file.

openapi: 3.0.0
info:
  title: Example API
  description: This is an example API to demonstrate a GET and POST endpoint.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /items:
    get:
      summary: Get list of items
      operationId: get-items # Attribute you need to reference in the slug.
      description: |
        Retrieves a list of items.

Step 4. Preview your Changes

Run the following command of our CLI to preview your changes in the local host.

writedocs dev

Step 5. Commit the Changes

Commit and push your changes to the main branch to see how your endpoint pages look published. To see your docs, follow the example below:

Repository name	Documentation URL
myCompany-docs	myCompany.docs.writedocs.io