Resolve "OpenAPI in dokument einpflegen"

Closes #11 (closed)

chapters/documentation.md

@@ -54,11 +54,28 @@ Call diagrams can be useful to follow code and service calls and should be exist
 
 - [Example for Java](https://lab.sub.uni-goettingen.de/self-updating-docs.html)
 
-- Links to callers must not be listed in the documentation, because this info will be deprecated soon. It is strongly
-recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Module (SADE).
+- Links to callers must not be listed in the documentation, because this info will be deprecated soon.
+It is strongly recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Module (SADE).
 
-- Document REST-APIs using [openAPI](https://github.com/OAI/OpenAPI-Specification) if possible. OpenAPI docs should be
-located at `/doc/api` on servers.
+- Document REST-APIs using [OpenAPI](https://github.com/OAI/OpenAPI-Specification) if possible.
+OpenAPI doc should be located at `/doc/api` on servers.
+We currently use OpenAPI for RESTXQ and JAX-RS service endpoints.
+
+##### OpenAPI for RESTXQ
+
+For documenting RESTXQ APIs in our eXist-db systems we use the [OpenAPI4RESTXQ](https://gitlab.gwdg.de/subugoe/openapi4restxq) application.
+It simply has to be installed in eXist-db and configured according to the [instructions](https://gitlab.gwdg.de/subugoe/openapi4restxq#use).
+
+##### OpenAPI for CXF Java JAXRS Applications
+
+We have not yet finished the OpenAPI documentation of our Java services, but a few tests with the [OpenAPI Feature of Apache CXF](https://cxf.apache.org/docs/openapifeature.html) have already been implemented.
+
+The outcome of this OpenAPI documentation shall be the automated generation of API doc, to be written directly IN THE CODE as Java Annotation, using the @Operation annotation, see [example](https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3_spring/src/main/java/demo/jaxrs/openapi/server/Sample.java#L65) and then to be read and directly be used from within a HTML page.
+An automatic generation of a [OpenAPI JSON file](https://dev.textgridlab.org/1.0/tgsearch-public/info/openapi.json) should be possible to use it with a [Swagger UI HTML page frontend](https://dev.textgridlab.org/1.0/tgsearch-public/info/api-docs/?url=/1.0/tgsearch-public/info/openapi.json).
+We can deliver that page with every service or we could deploy a central Swagger UI service for all the documentation.
+For every service endpoint an OpenAPI doc could be provided, such as already done for [TG-search](https://dev.textgridlab.org/1.0/tgsearch-public).
+
+We also can combine this OpenAPI doc with our existing Sphinx API documentation (such as the [TG-search Sphinx API documentation](https://textgridlab.org/doc/services/submodules/tg-search/docs/index.html) as you can find [here](https://sphinxcontrib-openapi.readthedocs.io)).
 
 #### CESSDA's Software Maturity Levels in RDD (CA1.3)
 
@@ -115,6 +132,7 @@ This may encompass:
 - guided tour (Bootstrap Tour) as user documentation
 
 - for SADE portal usage (such as Fontane, BdN, Architrave)
+
 - for complex Digital Editions
 
 - screencasts