OpenAPI Setup

Reference OpenAPI endpoints in your docs pages

Add an OpenAPI specification file

To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI document in either JSON or YAML format that follows the OpenAPI specification. Your document must follow OpenAPI specification 3.0+.

The method of setting up OpenAPI with Docuo is to add your OpenAPI documents directly to your docs repo. According to the following two parts:

1. Define an id to uniquely identify the OpenAPI document. The value must be a string of lowercase letters and digits
2. Then add the path of the OpenAPI document to the specPath field of the openapi config in your docuo.config.json:

{
  "openapi": {
    "id": {
      "specPath": "docs/Using OpenAPI/OpenAPI Demo/petstore.yaml",
      "outputDir": "docs/Using OpenAPI/OpenAPI Demo"
    }
  }
}

Create MDX files for OpenAPI endpoints

To add the OpenAPI endpoints into your docs, each endpoint requires a corresponding MDX file. You can autogenerate these MDX files from your OpenAPI documents using our CLI.

According to the following two parts:

1. Using the outputDir, specify the directory where MDX files corresponding to OpenAPI endpoints should be generated.

{
  "openapi": {
    "id": {
      "specPath": "docs/Using OpenAPI/OpenAPI Demo/petstore.yaml",
      "outputDir": "docs/Using OpenAPI/OpenAPI Demo"
    }
  }
}

2. Then run docuo's generate cli

docuo gen-openapi-docs

or alias:

docuo god

The generated mdx document is exactly like other documents. It can be configured in the sidebars file or automatically generated and added to the routing system. You can refer to the sidebars module.