Skip to content
Snippets Groups Projects
Commit f9fcb0a8 authored by Stefan E. Funk's avatar Stefan E. Funk
Browse files

fix: Correct typos and add crlf after each sentence

parent af112737
No related branches found
No related tags found
1 merge request!29Resolve "OpenAPI in dokument einpflegen"
Pipeline #145827 passed with warnings
...@@ -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)
- for complex Digital Editions - for complex Digital Editions
- screencasts - screencasts
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment