Source: https://undraw.co/

Exposing API DevPortals using Go-Swagger

Recently we had the Brazil's Central Banking publishing the regulation about OpenBanking. By October 2021, the expected 4 adoption milestones/phases must be ready. Lot's of good things ahead! One of the greatest tools that we added as part of our implementation framework to solve some challenges on this is actually Go-Swagger. In this post, I will show how to expose an astonishing API DevPortals using that tool

There are several installation options in the documentation here: https://goswagger.io/install.html . From docker to native binaries, like RPMs and also for MacOs using Homebrew, that's my case, so I installed using the very basic installation method as it follows:

Please, download the following content: https://raw.githubusercontent.com/skalena/openbankingBR/master/mexico/hsbc/swagger.json and create a file called api.json .

We used a Open API Spec file from a Bank from Mexico for that example.

If you type in the command line just the command swagger, you will see several options, in order to expose de DevPortal you can basically to use the following command (same folder where you saved the api.json file) :

The default API Docs will be exposed via this URL: http://localhost:62482/docs, see the following images:

DevPortal using ReDoc UI

Using Redoc and incrementing some extra properties, you can add your log, more information and etc. For the Golang ecosystem, I do recommend using Hugo as an offline/static CMS if you have to go further in the Documentation and Developer Experience.

If for some reason, you prefer the standard Swagger-UI, you can just use this command: swagger serve api.json — flavor=swagger , we use the parameter flavor to identity the API Doc renderer. For more configurations execute this command: swagger serve — help

Keep in mind that the best way to engage your Developers (consumers) is to offering a good experience when they have to deal with Developer's Portals. I already saw a company collecting user data (maybe for lead generation) as a requirement to show their DevPortal… Please, don't do that! Developers hate this kind of thing.

Another great aspect of investing in great API's contracts is to use tools like 42Crunch, which acts as an API Firewall(Scanning, Auditing, etc) helping you to discover breaches and potential critical security issues when you are exposing APIs.

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