Swagger-to-APIB.md

Prerequisites

fury is a tool for converting among different API documentation formats

Install fury-cli

npm install -g fury-cli

Install dos2unix

When running on OSX, there's an annoying thing with the way the conversion happens that leaves content with \r in there. (It might not be an issue in running on Linux, though!) This tool will strip them out.

brew install dos2unix

This repo also has some notes about how picky the format is:

• https://github.com/knockrentals/apidocs

Get the latest orm-cli

If you don't have it already, you should update to the latest version of the orm-cli

pip3 install --index-url https://nexus.common-build.gcp.oreilly.com/repository/pypi-group/simple --upgrade orm-cli

Doing the conversion

wget https://groot.platform-dev.gcp.oreilly.com/docs/api/swagger.json

fury --format text/vnd.apiblueprint swagger.json groot.apib

cat groot.apib | dos2unix >  groot2.apib
orm apib-lint groot2.apib
orm apib groot2.apib

Alternative conversion tools

• https://www.apimatic.io/transformer/ seems to be pretty good. They have an API you can use that's documented at https://www.apimatic.io/apidocs/cgaas-api/v/1_0#/python/getting-started

Additional Notes

Whew! Okay. Docs really are quite the adventure.

Regarding the triplicate rendering and trip-ups you found:

• Yes, the issue of the /r persists with apimatic (which I believe is the source of the resourceGroups error you pointed out above)
• That problem seems to be isolated to the particular renderer we chose, i.e Snowboard
• Snowboard also seems to struggle rendering both cardinal's apib file and groot's apib file. cardinal doesn't have the same triplicate problems, but some sections are just completely ignored which isn't great 😞 Regarding the link getting into surveyor: that's handled automatically in the chassis upon deploy. As long as there's an apib file and API_BLUEPRINT_PATH in the settings file it just happens in the background. The actual process of rendering the docs and such seems to touch into feather and perhaps another repo as well. At this point we need more exploration of our apib renderer before we can meaningfully use it. I hadn't circled back to the snowboard/surveyor set up until just now and it's clear our process is too brittle at the moment. I'm happy to work with the fine folks in #read-the-docs on this after my sprint commitments are met.