@@ -54,24 +54,26 @@ Call diagrams can be useful to follow code and service calls and should be exist
...
@@ -54,24 +54,26 @@ 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)
-[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
- Links to callers must not be listed in the documentation, because this info will be deprecated soon.
recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Module (SADE).
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.
- Document REST-APIs using [OpenAPI](https://github.com/OAI/OpenAPI-Specification) if possible.
OpenAPI docs should be located at `/doc/api` on servers.
OpenAPI doc should be located at `/doc/api` on servers.
We currently use OpenAPI for RESTXQ and JAX-RS service endpoints.
We currently use OpenAPI for RESTXQ and JAX-RS service endpoints.
##### OpenAPI for RESTXQ
##### OpenAPI for RESTXQ
For documenting RESTXQ APIs in our eXist-db systems we use the [OpenAPI4RESTXQ](https://gitlab.gwdg.de/subugoe/openapi4restxq)
For documenting RESTXQ APIs in our eXist-db systems we use the [OpenAPI4RESTXQ](https://gitlab.gwdg.de/subugoe/openapi4restxq) application.
application.
It simply has to be installed in eXist-db and configured according to the [instructions](https://gitlab.gwdg.de/subugoe/openapi4restxq#use).
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
##### 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.
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. A 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). The question is, if we deliver that page with every service or deploy a central Swagger UI service for all the documentation. For every service endpoint such a OpenAPI doc could be provided, such as already done for [TG-search](https://dev.textgridlab.org/1.0/tgsearch-public).
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)).
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)).
...
@@ -130,6 +132,7 @@ This may encompass:
...
@@ -130,6 +132,7 @@ This may encompass:
- guided tour (Bootstrap Tour) as user documentation
- guided tour (Bootstrap Tour) as user documentation
- for SADE portal usage (such as Fontane, BdN, Architrave)
- for SADE portal usage (such as Fontane, BdN, Architrave)