Bonita OpenAPI specification

Table of Contents

• Open API v3
• Live Documentation
  • Redoc Preview
  • Postman
• AWS Docker Deployment
• Local Docker Deployment
  • Script details
• Links
• Create a release
• How to contribute

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.

npm run yaml # (1)
npm run json # (2)

npm run build #(3)

1. result file is dist/openapi.yaml

2. result file is dist/openapi.json

3. clean, yaml & json steps

The specification file template 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.

Postman

Generate a Postman json based collection file

 npm run postman #(1)

1. result file is dist/postman.json

AWS Docker Deployment

Note

TODO

Local Docker Deployment

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 whole content, just issue run:

./dockerStart.sh

Script details

/dockerStart.sh

link:./dockerStart.sh[role=include]

/dockerStop.sh

link:./ansible/files/dockerStop.sh[role=include]

You should be able to access http://localhost:8084

Links

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

Create a release

A GitHub action is used to automate the release workflow. The workflow is triggered when pushing a branch with the following pattern release/<version>. The version should match the info.version attribute in openapi/openapi.yaml file.

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

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.