diff options
author | Benjamin Tissoires <benjamin.tissoires@redhat.com> | 2018-07-17 10:14:26 +0200 |
---|---|---|
committer | Benjamin Tissoires <benjamin.tissoires@redhat.com> | 2019-01-18 17:01:11 +0100 |
commit | 49d3eb5a3f21fad1eb2952eb3da2f93c5c5d6272 (patch) | |
tree | 63794ef5b81e5814387636563d4ae5d054269978 /openapi/README.md | |
parent | 889aa6d65208db2f3f364cc37a29be9325fa186a (diff) | |
download | wekan-49d3eb5a3f21fad1eb2952eb3da2f93c5c5d6272.tar.gz wekan-49d3eb5a3f21fad1eb2952eb3da2f93c5c5d6272.tar.bz2 wekan-49d3eb5a3f21fad1eb2952eb3da2f93c5c5d6272.zip |
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.
Diffstat (limited to 'openapi/README.md')
-rw-r--r-- | openapi/README.md | 27 |
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 |