Introducing the API Documentation (Swagger) Plugin 🧭

Today we are thrilled to release our freshly developed API Documentation Plugin 🔥 and let's face it, it has been a while since we released a new plugin for Strapi.

Even though it is still in alpha, many APIs are being created with Strapi and I believe that a good API comes with great documentation! Here comes the issue, and I can only guess what developers are going to say:

"Documenting is cool but at what cost?

Given that the minimum endpoints per content type is 6,

If I have 70 models in my API, do you expect me to write, by hand, the documentation for at least 420 paths??

I'm not crazy! Developers will find out how to use my API by themselves!

Well, good news! Your documentation can now be automated 🎉

The plugin had been developed some time ago but we weren't sure (until now) when we should release it.

After careful consideration, we thought that since we are working on a new plugin architecture, which might take us many months to complete, we should release it for free to help the community. In contrast, the other great plugins are baked.

Plus, since it's almost Christmas you can see this release as a Christmas gift from Strapi 🎅

Enough for the small talk; let's see what this plugin does!

Specifications

In fact, the Documentation Plugin is pretty simple, it parses all your model's routes (defined in my-strapi-project/api/**/config/routes.json), and also some of the plugins ones to generate an OpenAPI file. This very specific document will then be used by the Swagger UI so your development team or your end consumers — will visualize and interact with the API’s resources without having any of the implementation logic in place 🤩

This interface is rendered by Strapi and you have a whole set of options that goes from restricting the access of the documentation to customizing the default generated document. Before playing with the plugin, here's a reminder on how to get started with Strapi.

Thank again to @Martin Muzatko who updated our old doc 💙

Walkthrough

If you're new to Strapi, we recommend you to follow our Getting Started guide. Otherwise, you can follow the few steps below to use the new Documentation plugin.

1️⃣ Install the latest version:

1npm install strapi@alpha -g

2️⃣ Generate a new project and follow the configurations steps:

1strapi new my-project

3️⃣ Go to the root of the project, then install the Documentation plugin:

1strapi install documentation

4️⃣ Launch the server and create the first user:

1strapi start

To see the documentation, click on the Documentation link in the left menu, then on the "Open the Documentation" button and that's pretty much all you need to do to see your API's resources.

I have the feeling that this article is a bit short and since I'm feeling like writing a bit more let's go over some specific use cases.

Use Cases and Configurations

We are going to create some models using the Content Type Builder just for the sake of the example.

Create the following models:

👉 Product

• name (string)
• description (text)
• price (number)
• pictures (media) (select allow multiple files)

👉 Tag

• name (string)
• products (relation) (select Product on the right column and click on the many-to-many icon)

Let's create some products and tags by using the Content Manager!

At this point, if you click on the Documentation link, you can see that the plugin has generated the *1.0.0 documentation version of your API.

Visualise your API's resources:

Click on the "Open the Documentation" button and you will be redirected to the latest available version of your documentation. It's also available here.

Restrict the documentation access:

By default your documentation is public. If you wish to restrict the access, you can set a password in your administration panel.

Test your endpoints with Swagger UI:

Strapi is secured by default which means that if you did not modify your project's permissions you will need a valid jwtToken to consume your API. In order to test your endpoints using the Swagger UI you can copy your token from the Strapi Documentation administration panel, click on "Authorize" (in the Swagger UI), paste it and save. Now you can request your API with Swagger!

Generate a new documentation version

To generate a new version of your documentation you just need to change the version number in ./plugins/documentation/config/settings.json. So if I were to create the 3.0.0 version of the documentation, I would make the following modification:

If you've overrided the default documentation, you will have to copy the content of each overrided files in the new created folder for this version. For example, in each plugin you'll have to copy ./plugins/**/documentation/1.0.0/overrides/*.json into ./plugins/**/documentation/3.0.0/overrides/*.json.

Request another server

You may have a development, staging and production environments so if you want to change your host in Swagger UI you need to edit the ./plugins/documentation/config/settings.json file as follows:

Use Cases

Modifying the default generated response

Let's say that you have modified one handler of your Product's controller as follows:

The documentation plugin can't be aware that you added { foo: 'bar' } to the response so you will need to override this endpoint's (/products/count) response.

To do so, you will have to create a product.json file in ./api/product/documentation/1.0.0/overrides.

Then, you should see your documentation updated 🎉. The /products/count response should follow the schema defined in the file.

Changing the default tag of a custom endpoint

As you may have noticed, all your endpoints are grouped. For instance, you have a Product group and an Authentication one. Let's say you add a new endpoint called /dummy (because the use case I'm making is completely stupid...) in your ./api/product/config/routes.json file.

If you want that particular endpoint to be grouped under Dummy in your Swagger UI, you need to apply the following modifications in your ./api/product/documentation/1.0.0/overrides/product.json file.

Creating a custom endpoint that references another model and automate its response

Now let's say that I want to create a custom endpoint in my Product model that counts the total number of uploaded files and I want the plugin to generate the response automatically and group this endpoint with all the Upload - File available ones.

Then, you need to update the ./api/product/config/routes.json file as well.

You can notice the new tag property in the configuration of the route.

• name references the File model
• plugin tells the algorithm to retrieve the model from the Upload plugin
• actionType makes an assumption on the count response

You should see your documentation updated 🎉. The new /countFiles endpoint should be grouped with the Upload - File ones.

I hope you enjoyed testing the Documentation plugin in this tutorial. As you can imagine, there is plenty of other uses cases so please refer to the documentation to know more and feel free to hit us up on Discord, Twitter, Facebook or GitHub.

And if you enjoyed it, please give us a star on GitHub, we'd love to reach the 10000 stars for Christmas #strapiXmaschallenge!

Thanks and wish you a great holiday season!