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, …​

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.

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 interesting to test and evaluate different sites and rendering.

You 'll need to install the openapi-cli to be able to work on the specification.

Open API documentation:

https://swagger.io/docs/specification/basic-structure/

IDE support:

• intellij: https://www.jetbrains.com/help/idea/openapi.html

• eclipse: https://marketplace.eclipse.org/category/free-tagging/openapi

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

• https://github.com/Redocly/redoc

A GitHub action is used to automate the release workflow. The workflow is triggered by user action and you need to choose the release type (following semver).

A GitHub release is created with the yaml specification file, the json postman collection and the static documentation zip attached. Release note must be filled manually.

To deploy your newest release on the documentation site, you need to:

• On rest documentation config, add the released version for each compatible Bonita version.

• Open a PR and asked for a review.

• Follow updates on your PR, and also to update openApiLatestVersion: in antora.yml file for each Bonita documentation content corresponding branches.

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.

When you open a pull request, keep in mind to add labels to help the release-note content writing automatically. Labels available are :