Creating an open API documentation
In our Docusaurus-openAPI-docs Plugin section, we give you an introduction about the method we use to generate documentation pages
from yaml
definitions. We strongly suggest you to check that section where you can find links to the plugin documentation and take a general overview of the results we are gaining from it.
In this guideline
page we describe the steps to generate the .mdx
files from the yaml
definitions, that later will be translated in to documentation pages
by Docusaurus.
In our example we are going to:
- Define our openAPI methods in the
openAPI.yaml
located in theroot
folder from our project. - Generate
.mdx
files with the plugin in our/docs-kits/kits/exampleKIT/SoftwareDevelopmentView/exampleAPI
folder.
Like mentioned, the first step is to define the desired methods that are in our interest to describe in a
yaml
file. In our case the name of the file isopenAPI.yaml
located in theroot
folder.In the
Docusaurus.config.js
a required plugin's set up is already defined, you'd need to provided under theplugins
array a new instance in the 'config' object, like following:{
plugins: [
[
'docusaurus-plugin-openapi-docs',
{
id: "docs-kits",
docsPluginId: "docs-kits",
config: {
//*************** add the bellow declaration with your specific instance data ******************
exampleController: { // modify with unique id
specPath: "./openAPI.yaml", // Path to designated spec file
outputDir: "./docs-kits/kits/exampleKIT/SoftwareDevelopmentView/exampleAPI", // Output directory for generated .mdx docs
sidebarOptions: {
groupPathsBy: "tag",
},
// **********************************************************************************************
},
// Other instances...
},
}
],
],
}Now making use of the
CLI
we just need to provide the nextcommand
:
npm run docusaurus gen-api-docs exampleController
After the command runs, in the designated folder /docs-kits/kits/exampleKIT/SoftwareDevelopmentView/exampleAPI
, one .mdx
file will be generated for each method described in the openAPI.yaml
file.
NOTE This is a brief description of the main steps to generate documentation pages
as docs in our project, there are several options and commands that can be passed to configure the .mdx
files generation. Please check the docusaurus-openAPI-docs