documentation for api

docs/source/development/api.rst

@@ -450,4 +450,39 @@ Full configuration example
                        single-collection: single
                base_role: null
 
+Maintaining an OpenApi
+======================
+
+.. note::
+
+   This is experimental and may change. Keep reading this part.
+
+Accessing swagger
+-----------------
+
+The swagger UI is accessible through `<http://localhost:8001/_dev/swagger>`_
+
+This is possible only in development mode.
+
+You must be authenticated with a valid user to access it.
+
+Maintaining specs
+-----------------
+
+Each bundle should have an `open api 3.0 spec file <https://swagger.io/docs/specification/about/>`_ at the bundle's root, and name :code:`chill.api.specs.yaml`.
+
+.. warning::
+
+   Update the command :code:`specs-build` into `package.json` when adding a new api file.
+
+The specs may be compiled from the different bundles filed, and validated using docker node:
+
+.. code-block:: bash
+
+   ./docker-node.sh
+   # build the openapi
+   yarn specs-build
+   # validate
+   yarn specs-validate
+