Bonita OpenAPI specification
This project is about describing the Bonita web API in Open API v3 format.
This single yaml file is to become the single source of truth for the Bonita features accessible through HTTP.
Based on this file, one could generate : documentation, client in different language and/or technology, server side stubs, …
Open API v3
The specification file is written in yaml
format because multiline support is much better than in json
The specification has a lot of description block and since it is a documentation, it needs to be quite verbose.
The specification file can be found here: openapi/openapi.yaml
We make use of extensions to add better support for some documentation sites (x-logo, x-codeSamples, …)
This repository structure was inspired by https://github.com/Redocly/create-openapi-repo.
Live Documentation
The api descriptor file can be used to render documentation sites. Those sites have different rendering and may show different parts of the specification file. That’s the reason why it is interessting to test and evaluate differents sites and rendering.
You 'll need to install the openapi-cli to be able to work on the specification.
Redoc Preview
A ReDoc site is available at http://localhost:8080 when you run from project directory
npm start
This preview is the preferred one when editing the specification.
Swagger Preview
The docker-compose.yaml
file at the project root starts two sites: a swagger-ui site and a Bonita instance to query
To start the container, just issue the following comment at the project root:
docker-compose up -d
You should be able to access:
-
Bonita: http://bonita.localhost/bonita
-
Swagger UI: http://swagger.localhost
You can keep on editing the specification file and just refresh the browser to see the changes. |
Links
Open API documentation:
IDE support:
Specification samples:
-
Docker API: https://docs.docker.com/engine/api/v1.40/
-
Discourse API: https://docs.discourse.org/
-
API hub: https://apis.guru/browse-apis/
-
Samples: https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v3.0
ReDoc
How to contribute
We would love you to contribute, pull requests are welcome!
Have a look to DEV.md guidelines and don’t forget to sign our Contributor Licensing Agreements when opening a pull request.
This repository uses Github flow, so pull requests should target the master
branch.