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
Installing Go-Swagger
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:
Exposing a DevPortal from existing Swagger/OAS
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:
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
Conclusion
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.
