Page summary:

The Documentation plugin auto-generates OpenAPI/Swagger docs for your API by scanning content types and routes. This documentation walks you through installation, customizing settings, and restricting access to the docs.

The Documentation plugin automates your API documentation creation. It basically generates a swagger file. It follows theOpen API specification version.

If installed, the Documentation plugin will inspect content types and routes found on all APIs in your project and any plugin specified in the configuration. The plugin will then programmatically generate documentation to match theOpenAPI specification. The Documentation plugin generates thepaths objects andschema objects and converts all Strapi types toOpenAPI data types.

The generated documentation JSON file can be found in your application at the following path:src/extensions/documentation/documentation/<version>/full_documentation.json

Installation​

To install the documentation plugin, run following command in your terminal:

yarnadd @strapi/plugin-documentation

npminstall @strapi/plugin-documentation

Once the plugin is installed, starting Strapi generates the API documentation.

Configuration​

Most configuration options for the Documentation plugin are handled via your Strapi project's code. A few settings are available in the admin panel.

Admin panel settings​

The Documentation plugin affects multiple parts of the admin panel. The following table lists all the additional options and settings that are added to a Strapi application once the plugin has been installed:

Restricting access to your API documentation​

By default, your API documentation will be accessible by anyone.

To restrict API documentation access, enable the Restricted Access option from the admin panel:

1. Navigate toSettings in the main navigation of the admin panel.
2. ChooseDocumentation.
3. ToggleRestricted Access to ON.
4. Define a password in the password input.
5. Save the settings.

Code-based configuration​

To configure the Documentation plugin, create asettings.json file in thesrc/extensions/documentation/config folder. In this file, you can specify all your environment variables, licenses, external documentation links, and all the entries listed in thespecification.

The following is an example configuration:

{
"openapi":"3.0.0",
"info":{
"version":"1.0.0",
"title":"DOCUMENTATION",
"description":"",
"termsOfService":"YOUR_TERMS_OF_SERVICE_URL",
"contact":{
"name":"TEAM",
"email":"contact-email@something.io",
"url":"mywebsite.io"
},
"license":{
"name":"Apache 2.0",
"url":"https://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"x-strapi-config":{
"plugins":["upload","users-permissions"],
"path":"/documentation"
},
"servers":[
{
"url":"http://localhost:1337/api",
"description":"Development server"
}
],
"externalDocs":{
"description":"Find out more",
"url":"https://docs.strapi.io/developer-docs/latest/getting-started/introduction.html"
},
"security":[
{
"bearerAuth":[]
}
]
}

Creating a new version of the documentation​

To create a new version, change theinfo.version key in thesettings.json file:

{
"info":{
"version":"2.0.0"
}
}

This will automatically create a new version.

Defining which plugins need documentation generated​

If you want plugins to be included in documentation generation, they should be included in theplugins array in thex-strapi-config object. By default, the array is initialized with["upload", "users-permissions"]:

{
"x-strapi-config":{
"plugins":["upload","users-permissions"]
}
}

To add more plugins, such as your custom plugins, add their name to the array.

If you do not want plugins to be included in documentation generation, provide an empty array (i.e.,plugins: []).

Overriding the generated documentation​

The Documentation plugins comes with 3 methods to override the generated documentation:excludeFromGeneration,registerOverride, andmutateDocumentation.

excludeFromGeneration()​

To exclude certain APIs or plugins from being generated, use theexcludeFromGeneration found on the documentation plugin’soverride service in your application or plugin'sregister lifecycle.

module.exports={
register({ strapi}){
    strapi
.plugin("documentation")
.service("override")
.excludeFromGeneration("restaurant");
// or several
    strapi
.plugin("documentation")
.service("override")
.excludeFromGeneration(["address","upload"]);
}
}

registerOverride()​

If the Documentation plugin fails to generate what you expect, it is possible to replace what has been generated.

The Documentation plugin exposes an API that allows you to replace what was generated for the following OpenAPI root level keys:paths,tags,components .

To provide an override, use theregisterOverride function found on the Documentation plugin’soverride service in your application or plugin'sregister lifecycle.

The Documentation plugin will use the registered overrides to replace the value of common keys on the generated documentation with what the override provides. If no common keys are found, the plugin will add new keys to the generated documentation.

If the override completely replaces what the documentation generates, you can specify that generation is no longer necessary by providing the names of the APIs or plugins to exclude in the options key arrayexcludeFromGeneration.

If the override should only be applied to a specific version, the override must include a value forinfo.version. Otherwise, the override will run on all documentation versions.

module.exports={
register({ strapi}){
if(strapi.plugin('documentation')){
const override={
// Only run this override for version 1.0.0
info:{version:'1.0.0'},
paths:{
'/answer-to-everything':{
get:{
responses:{200:{description:"*"}}
}
}
}
}

      strapi
.plugin('documentation')
.service('override')
.registerOverride(override,{
// Specify the origin in case the user does not want this plugin documented
pluginOrigin:'upload',
// The override provides everything don't generate anything
excludeFromGeneration:['upload'],
});
}
},
}

The overrides system is provided to try and simplify amending the generated documentation. It is the only way a plugin can add or modify the generated documentation.

mutateDocumentation()​

The Documentation plugin’s configuration also accepts amutateDocumentation function oninfo['x-strapi-config']. This function receives a draft state of the generated documentation that be can be mutated. It should only be applied from an application and has the final say in the OpenAPI schema.

module.exports={
documentation:{
config:{
"x-strapi-config":{
mutateDocumentation:(generatedDocumentationDraft)=>{
          generatedDocumentationDraft.paths[
"/answer-to-everything"// must be an existing path
].get.responses["200"].description="*";
},
},
},
},
};

Usage​

The Documentation plugin visualizes your API usingSwagger UI. To access the UI, select in the main navigation of the admin panel. Then clickOpen documentation to open the Swagger UI. Using the Swagger UI you can view all of the endpoints available on your API and trigger API calls.

Regenerating documentation​

There are 2 ways to update the documentation after making changes to your API:

• restart your application to regenerate the version of the documentation specified in the Documentation plugin's configuration,
• or go to the Documentation plugin page and click the regenerate button for the documentation version you want to regenerate.

Authenticating requests​

Strapi is secured by default, which means that most of your endpoints require the user to be authorized. If the CRUD action has not been set to Public in theUsers & Permissions feature then you must provide your JSON web token (JWT). To do this, while viewing the API Documentation, click theAuthorize button and paste your JWT in thebearerAuthvalue field.