README.adoc 3.78 KB
Newer Older
Romain Bioteau's avatar
Romain Bioteau committed
1
2
= Bonita OpenAPI specification

Romain Bioteau's avatar
Romain Bioteau committed
3
image:https://github.com/bonitasoft/bonita-openapi/workflows/build/badge.svg[Actions Status, link=https://github.com/bonitasoft/bonita-openapi/actions?query=build]
Romain Bioteau's avatar
Romain Bioteau committed
4
5
image:https://img.shields.io/github/v/release/bonitasoft/bonita-openapi?color=blue&label=Release[GitHub release, link=https://github.com/bonitasoft/bonita-openapi/releases]
image:https://img.shields.io/badge/License-GPL%20v2-blue.svg[GPLv2 License, link=LICENSE]
hugues.bretin's avatar
hugues.bretin committed
6
7
8
9
10

This project is about describing the Bonita web API in https://swagger.io/specification/[Open API v3] format.

This single yaml file is to become the single source of truth for the Bonita features accessible through HTTP.

hugues.bretin's avatar
hugues.bretin committed
11
Based on this file, one could generate : documentation, client in different language and/or technology, server side stubs, ...
hugues.bretin's avatar
hugues.bretin committed
12
13
14
15
16
17

== 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.

hugues.bretin's avatar
hugues.bretin committed
18
The specification file can be found here: `openapi/openapi.yaml`
hugues.bretin's avatar
hugues.bretin committed
19
20
21

We make use of https://swagger.io/docs/specification/openapi-extensions/[extensions] to add better support for some documentation sites (x-logo, x-codeSamples, ...)

hugues.bretin's avatar
hugues.bretin committed
22
23
This repository structure was inspired by https://github.com/Redocly/create-openapi-repo.

hugues.bretin's avatar
hugues.bretin committed
24
25
26
27
28
== 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.

hugues.bretin's avatar
hugues.bretin committed
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
You 'll need to install the https://github.com/redocly/openapi-cli[openapi-cli] to be able to work on the specification.

=== Redoc Preview

A https://github.com/Redocly/redoc[ReDoc] site is available at http://localhost:8080 when you run from project directory

[source,bash]
----
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 https://swagger.io/tools/swagger-ui/[swagger-ui] site and a Bonita instance to query
hugues.bretin's avatar
hugues.bretin committed
45
46
47
48
49
50
51
52
53
54

To start the container, just issue the following comment at the project root:

[source,bash]
----
docker-compose up -d
----

You should be able to access:

hugues.bretin's avatar
hugues.bretin committed
55
56
- Bonita: http://bonita.localhost/bonita
- Swagger UI: http://swagger.localhost
hugues.bretin's avatar
hugues.bretin committed
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

NOTE: You can keep on editing the specification file and just refresh the browser to see the changes.

== 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/
hugues.bretin's avatar
hugues.bretin committed
76
77
78
79
- Samples: https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v3.0

*ReDoc*

Romain Bioteau's avatar
Romain Bioteau committed
80
81
- https://github.com/Redocly/redoc

Romain Bioteau's avatar
Romain Bioteau committed
82
83
84
85
== Create a release

A GitHub action is used to automate the link:.github/workflows/release.yml[release workflow].
The workflow is triggered when pushing a branch with the following pattern `release/<version>`.
Romain Bioteau's avatar
Romain Bioteau committed
86
The `version` should match the `info.version` attribute in link:openapi/openapi.yaml[] file.
Romain Bioteau's avatar
Romain Bioteau committed
87
88
89
90

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

Romain Bioteau's avatar
Romain Bioteau committed
91
92
== How to contribute

Romain Bioteau's avatar
Romain Bioteau committed
93
94
We would love you to contribute, pull requests are welcome! 
Have a look to link:DEV.md[] guidelines and don't forget to sign our Contributor Licensing Agreements when opening a pull request.
Romain Bioteau's avatar
Romain Bioteau committed
95
This repository uses https://guides.github.com/introduction/flow/[Github flow], so pull requests should target the `master` branch.