mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-02-07 12:51:37 -05:00
3968eedcc5
* refactor some pkg/jmap and groupware methods to make more sense from an API point-of-view * add path parameter documentation, but automate it by injecting their definition into the OpenAPI YAML tree that is extracted from the source code using go-swagger as it is too cumbersome, repetitive and error-prine to document them in the source code; wrote a TypeScript file apidoc-process.ts to do so * add generating an offline HTML file for the OpenAPI documentation using redocly, and injecting a favicon into the resulting HTML; wrote a TypeScript file apidoc-postprocess-html.ts to do so
31 lines
1.4 KiB
Markdown
31 lines
1.4 KiB
Markdown
# Groupware
|
|
|
|
The OpenCloud Groupware service provides a REST API for performing all the backend operations needed by the OpenCloud Groupware frontends.
|
|
|
|
## OpenAPI Documentation
|
|
|
|
To generate the OpenAPI ("Swagger") documentation of the REST API, [`pnpm`](https://pnpm.io/) is a pre-requisite.
|
|
|
|
Run the following command in this directory to generate the `swagger.yml` OpenAPI definition file:
|
|
|
|
```bash
|
|
make apidoc
|
|
```
|
|
|
|
To generate a static HTML file using [Redocly](https://redocly.com/), which will generate a file `api.html`:
|
|
|
|
```bash
|
|
make apidoc-static
|
|
```
|
|
|
|
### Path Parameters
|
|
|
|
Path parameters are documented in the file [`api-params.yaml`](file:api-params.yaml) and injected into the OpenAPI specification using the script [`apidoc-process.ts`](file:apidoc-process.ts) (which is done automatically when using the `Makefile` as described above.)
|
|
|
|
### Favicon
|
|
|
|
A [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) is inserted into the static (Redocly) HTML file as part of the build process in the `Makefile`, using [`favicon.png`](file:favicon.png) as the source, computing its base64 to insert it as an image using a [data URL](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data) in order to embed it.
|
|
|
|
That is performed by the script [`apidoc-postprocess-html.ts`](file:apidoc-postprocess-html.ts) (which is done automatically when using then `Makefile` as described above.)
|
|
|