Skip to content
Snippets Groups Projects

Resolve "OpenAPI in dokument einpflegen"

Merged Resolve "OpenAPI in dokument einpflegen"
11-openapi-in-dokument-einpflegen into master
All threads resolved!
Merged Michelle Weidling requested to merge 11-openapi-in-dokument-einpflegen into master
All threads resolved!
Viewing commit f9fcb0a8
Prev
Show latest version
1 file
+ 10
− 7
Compare changes
  • Side-by-side
  • Inline
chapters/documentation.md
+ 10
− 7
@@ -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)
- 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.
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.
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.
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)).
@@ -130,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