fury is a tool for converting among different API documentation formats
npm install -g fury-cli
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:
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
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
- 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
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.