Add OpenAPI description of the REST API

The API is generated by a custom script that parses the models directory.
Once the API is generated, tools like https://editor.swagger.io/ or
Python bravado can parse the file and generate a language friendly API.

Note that the tool generate an OpenAPI 2.0 version because bravado
doesn't handle OpenAPI 3.0.

The script also parses the JSDoc with a custom parser to allow
customization of the description of the fields.

1 files changed, 27 insertions, 0 deletions

diff --git a/openapi/README.md b/openapi/README.md
new file mode 100644
index 00000000..c353ffd4
--- /dev/null
+++ b/openapi/README.md
@@ -0,0 +1,27 @@
+
+# OpenAPI tools and doc generation
+
+## Open API generation
+
+This folder contains a script (`generate_openapi.py`) that extracts
+the REST API of Wekan and exports it under the OpenAPI 2.0 specification
+(Swagger 2.0).
+
+### dependencies
+- python3
+- [esprima-python](https://github.com/Kronuz/esprima-python)
+
+### calling the tool
+
+    python3 generate_openapi.py --release v1.65 > ../public/wekan_api.yml
+
+## Generating docs
+Now that we have the OpenAPI, it's easy enough to convert the YAML file into some nice Markdown with
+[shins](https://github.com/Mermade/shins) and [api2html](https://github.com/tobilg/api2html),
+or even [ReDoc](https://github.com/Rebilly/ReDoc):
+
+    api2html -c ../public/wekan-logo-header.png -o api.html ../public/wekan_api.yml
+
+or
+
+    redoc-cli serve ../public/wekan_api.yml