New Swagger API doc

New OBS API Documentation

We are rewriting our documentation using Swagger.

As a guide, we are using: https://swagger.io/docs/specification/about/

The main configuration file is here: https://github.com/openSUSE/open-build-service/blob/master/src/api/public/apidocs/OBS-v2.10.50.yaml

How to test it

Start the development environment and point your browser to http://localhost:3000/apidocs/index.html

If you introduce any change in the documentation and then refresh the page, you might not see the changes applied. That is related to cache and this is our workaround:

How to update

• Download the latest .tar.gz file from https://github.com/swagger-api/swagger-ui/tags .
• Repeat the installation instructions, overwriting the files from the dist/ folder of the tar file into src/api/public/apidocs/
• Don't forget, inside the swagger-initializer.js file:
  • replace the URL with url: "OBS-v2.10.50.yaml",, and
  • prevent from showing the file explorer, replacing layout: "StandaloneLayout" with showExplorer: false,, and
  • disable the validator, adding: validatorUrl: "none",
• Create the pull request. Take this one as example: https://github.com/openSUSE/open-build-service/pull/10957

CAVEATS

Some people experience problems with Swagger and Rails, specially when a file get changed, either Rails doesn't reload it or browser caches it. To the second issue, normally running the browser in incognito/private mode helps. In Chrome, disabling the cache under the Network tab in the developer tools also helps.

How we resolve the swagger yaml references to speed up rendering times in production

For development purposes it is handy to split up the docs into many yaml files and then reference to those, in order to keep the diffs small and reviewable. But it turned out to lead to slow rendering times over time, since we have one http request for each yaml file. Thats why we resolve those references during the build of the obs-server package that we use in production scenarios, and create one big yaml file that the swagger-ui loads and renders. We created a custom script for this purposes which can be found here. It is called during the build process from here and replaces the development version we point to from swagger-initializer.js.