New Swagger API doc
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-new/OBS-v2.10.50.yaml
Start the development environment and point your browser to http://localhost:3000/apidocs-new/index.html
In the development environment, when you introduce some changes in the API documentation you won't see them applied after refreshing the page. That is related to cache and this is our workaround:
- 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 intosrc/api/public/apidocs-new/ - Don't forget to replace the URL inside the
swagger-initializer.jsfile with'OBS-v2.10.50.yaml'. - Create the pull request. Take this one as example: https://github.com/openSUSE/open-build-service/pull/10957
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.