Engaging audience with great API Developer Portals

Edgar A Silva

Oct 22·4 min read

About every single organization is promoting an API initiative, in that case, just having a great and functional API might be not enough to attract and engage potential consumers. Even the APIs with fabulous Swaggers, sometimes might lack detailed information and documentation for developers, being in how to use the API’s SDKs, or simply documentation more in-depth. In this post, we will show a great tool to help both in API Dev Portal, and why not, your whole Developer Experience — DevExp.

Generating the APIs Documentation while Coding

Developers are intended to be no big fans to document their things. If you work with people like that, please buy them a coffee every day. For that reason, it is extremely important you get the docs and information about the APIs, while Developers are developing them.

If you rely on some API Manager products, some of them fail miserably in that APIs Developer's Portal aspect. In order to let this process more independent from any API Product, we would like to introduce you to Docusarus: https://v2.docusaurus.io/

Docusaurus is a great tool, because it combines the markdown text format for editing your documents, as well as it has the power to extend it using the popular framework React. In addition, it does support to render the API definitions, being both Swagger formats (json-v2.0), or Open API Spec (Yamls-v3.x).

We recommend, that the developers that are creating their APIs, could create their MD's docs, where through a CI/CD process, you can get those markdowns to generate the API DevPortal automatically. This post, can show you how to do this combining Azure DevOps, S3 and CI/CD practices:

Basics in how to Integrate Swagger with your Doc's Portal

The installation's process is extremely straightforward, into a terminal window, create a new folder, and type the following code:

npx @docusaurus/init@next init mydevportal classic

That will generate the following site structure for you:

├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Inside the folder docs, you will find the markdown files, and there you can add your own. In order to check how it is going so far, let's run our site using NPM, as the following commands in your terminal:

$ npm run start
  ✔ Client
  Compiled successfully in 8.25s

ℹ ｢wds｣: Project is running at http://localhost:3000/
ℹ ｢wds｣: webpack output is served from /
ℹ ｢wds｣: Content not from webpack is served from /Users/edgar/Documents/DEV-2/2020/mydevportal
ℹ ｢wds｣: 404s will fallback to /index.html

✔ Client
  Compiled successfully in 94.08ms

Here is our Developer Portal so far:

Here the documentation content in dark mode:

Adding Swagger/OAS Support to your Docusaurus Dev Portal

The lonely thing you have to do is to add some libraries to your project, as we used NPM once, let's use Yarn now:

$ yarn add @docusaurus/mdx-loader
$ yarn add swagger-ui-react

The command above will add the support to render the Swagger UI into your md pages inside your developer portal website.

Last Steps

Now, let's just create the md file, but now, adding the reference to the Swagger. Notice, what we are using some React inside the Markdown, please create this called as swagger.md inside the docs folder:

Please, invoke the npm run start again, and check the results:

Conclusion

An effective API Dev Portal, and in general a Developer Portal with samples, in-depth documentation can be a key component for your engagement strategy. Docusaurus is a great opensource solution, maintained by simply Facebook (https://github.com/facebook/docusaurus). In the next post, I will try to show a similar technique, but using Hugo(https://gohugo.io) as static sites generators using markdown. See you next.

Interested in some great information about APIs, in general, take a look on this: https://skalena.github.io/api-methodology/public/basics/