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-new/OBS-v2.10.50.yaml

How to test it

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

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-new/
• Don't forget to replace the URL inside the index.html file with 'OBS-v2.10.50.yaml'.
• 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.