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+. Then add your OpenAPI documents directly to your docs repo.

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

{
  "openapi": {
    "petstore": {
      "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 with Docuo CLI.

According to the following two parts:

1. Specify the directory where MDX files corresponding to OpenAPI endpoints should be generated with outputDir.

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

2. Then run the generate command

docuo gen-openapi-docs

docuo god

After the generation process is completed, you will probably see a similar files output:

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.