Image for post
Image for post
https://www.akana.com/sites/akana/files/image/2019-06/image-blog-developing-api-strategy-600x400.jpg

Engaging audience with great API Developer Portals

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.

Engaging your Developers and API Consumers

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/

Image for post
Image for post
Docusaurus version 2.0

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:

Image for post
Image for post
Docusaurus Home Page

Here the documentation content in dark mode:

Image for post
Image for post
Doc 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:

Image for post
Image for post
Now, docusaurus is rendering the Swagger from Petstore
Image for post
Image for post
Day/White Theme

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/

Just a dad, a husband, and an Old-School Brazilian Jiu-Jitsu Black-belt. Working in the technology field since 1997.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store