o2r Web API

Project description: https://o2r.info

Basics

We're a research project, so everything in this API and its documentation is subject to change. The "working" state should always be in the master branch, which is published online at https://o2r.info/api, and open pull requests reflect features under development.

API docs

This specification follows the Open API 3.0.3 specification. It is written in YAML and deployed automatically using ReDoc. See the ReDoc documentation for details.

View

The docs are build dynamically based on openapi.yml when index.html is opened in a browser. You can do this locally by starting a web browser in the /docs directory:

docker run --rm -it -v $(pwd)/docs:/usr/share/nginx/html:ro nginx

Then open http://localhost/index.html.

Build

You can render the openapi.yml in this repository with redoc-cli tool. The output is a a zero-dependency static HTML file in your current directory.

#npm i -g redoc-cli

redoc-cli bundle docs/openapi.yml

⚠️ This will not include our style changes!

Our combination of the openapi.yml and ReDoc's redoc.standalone.js will render a html which is then deployed via the /docs folder. Our script redoc_theme.js contains the actual ReDoc initialization command and makes a few style changes through callback functions to correspond to our project. The css rules which expand the core ReDoc style are in the openapi_style.css file.

Github pages build

The pages at https://o2r.info/api/ are built locally by developers on relevant changes. The website is served from the directory /docs, which must be configured in the repository settings.

Develop locally

You can serve the HTML page (without style changes!) and automatically re-rendering on changes with

redoc-cli serve --watch docs/openapi.yml

PDF Generation

Note that for every commit on the master branch a new PDF document will be generated. This can quickly lead to many commits. So it is best to develop new features on other branches.

License

The o2r Web API specification is licensed under Creative Commons CC0 1.0 Universal License, see file LICENSE. To the extent possible under law, the people who associated CC0 with this work have waived all copyright and related or neighboring rights to this work. This work is published from: Germany.