DOC: Document the XML API

Summary

See https://gitlab.indiscale.com/caosdb/customers/lfpb/management/-/issues/238 and https://gitlab.indiscale.com/caosdb/customers/lfpb/management/-/issues/407. Introduce a minimal documentation of the specifications of the XML API using openAPI.

Focus

The formulation of the API is in src/doc/development/api/xml/caosdb_openapi.yaml. Some text and a new section for the entity API have been added to the Specifications section, but since openapi-codegen fails to produce reasonable output, we leave it to gitlab to render the specification and just link to the file blob.

Test Environment

make doc and have a look at the section in Specification.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related Issues
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there spezifications? Are they satisfied?

For further good practices have a look at our review guidelines.

src/doc/development/api/xml/Makefile

+# This file is a part of the CaosDB Project.
+#
+# Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
+# Copyright (C) 2021 Daniel Hornung <d.hornung@indiscale.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+# Build to sphinx' static dir
+BUILDDIR      ?= ../../../_static/api/xml/
+
+
+.PHONY: doc
+doc:
+	mkdir -p $(BUILDDIR)
+	[ -e openapi-generator-cli.jar ] || wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.1.0/openapi-generator-cli-5.1.0.jar -O openapi-generator-cli.jar
+	java -jar openapi-generator-cli.jar generate -i caosdb_openapi.yaml --config openapi_config.json -g html2 -o $(BUILDDIR)
+
+
+
+## Not needed (the same code anyway?)
+
+# [ -e swagger-codegen-cli.jar ] || wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.27/swagger-codegen-cli-3.0.27.jar -O swagger-codegen-cli.jar
+# java -jar swagger-codegen-cli.jar generate -i caosdb_openapi.yaml -l html2 -o $(BUILDDIR)