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.

Image for post
Image for post
Engaging your Developers and API Consumers

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:

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

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.

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

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/

Written by

Just a dad, husband, and an Old-School Brazilian Jiu-Jitsu Black-belt. Skalena Founder, former WSO2, MuleSoft, Oracle, RedHat, Sun, Borland

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