diff --git a/.gitignore b/.gitignore
index 6ebd032b84c79dfa2a4bbf4df81cadce8a2a1555..2b4a625324a2696c6ff9d8ecf55254451d57ef9c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,6 +17,8 @@ build/
bin/
target/
_apidoc/
+src/doc/development/api/xml/out/
+src/doc/_static/api/
# But include server-side scripting
!/scripting/bin
@@ -39,3 +41,6 @@ authtoken/
# python
__pycache__
*~
+
+# Documentation binaries
+src/doc/development/api/xml/*.jar
diff --git a/.gitlab/merge_request_templates/Default.md b/.gitlab/merge_request_templates/Default.md
index a8c5b719ad5f8e18c2fd68d2daa1e5c62f94d450..ac68afc814247e5a64395315e630d5de44a5f306 100644
--- a/.gitlab/merge_request_templates/Default.md
+++ b/.gitlab/merge_request_templates/Default.md
@@ -40,7 +40,7 @@ guidelines](https://gitlab.com/caosdb/caosdb/-/blob/dev/REVIEW_GUIDELINES.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?
+- [ ] Check: Are there specifications? Are they satisfied?
For further good practices have a look at [our review guidelines](https://gitlab.com/caosdb/caosdb/-/blob/dev/REVIEW_GUIDELINES.md).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 698408a6f92ede94a957a5e302eeb5b6b8a36978..9269fd416dfedb5e532a0fc53cbf3549f145eecc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+* An openAPI specification of the XML api
+
### Changed
### Deprecated
@@ -17,7 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
-- #145 Documentation of importances and inheritance
+* #145 Documentation of importances and inheritance
+* Missing sources of the easy-unit dependency.
### Security
diff --git a/Makefile b/Makefile
index 1543286b67c6c7be20772a3b6932b9e0dcec27d5..7cafdb949cc213d1468383ce7c6a280452ef9904 100644
--- a/Makefile
+++ b/Makefile
@@ -129,7 +129,7 @@ stop-debug-screen:
easy-units: .m2-local
mvn clean
- mvn deploy:deploy-file -DgroupId=de.timmfitschen -DartifactId=easy-units -Dversion=0.0.1-SNAPSHOT -Durl=file:./.m2-local/ -DrepositoryId=local-maven-repo -DupdateReleaseInfo=true -Dfile=./lib/easy-units-0.0.1-SNAPSHOT-jar-with-dependencies.jar
+ mvn deploy:deploy-file -DgroupId=de.timmfitschen -DartifactId=easy-units -Dversion=0.0.1 -Durl=file:./.m2-local/ -DrepositoryId=local-maven-repo -DupdateReleaseInfo=true -Dfile=./lib/easy-units-0.0.1-jar-with-dependencies.jar
# Compile the standalone documentation
.PHONY: doc
diff --git a/README_SETUP.md b/README_SETUP.md
index 81816e3c9cc43b9ed8de47bba5a3e8202a8cfa35..afc63592e7797adafa8cd58df37d0aff0a8d5b15 100644
--- a/README_SETUP.md
+++ b/README_SETUP.md
@@ -118,7 +118,7 @@ server:
- `INSERT_FILES_IN_DIR_ALLOWED_DIRS`: add mounted filesystems here that
shall be accessible by CaosDB
* Maybe set another `SESSION_TIMEOUT_MS`.
- * See also [README_CONFIGURATION.md](README_CONFIGURATION.md)
+ * See also [CONFIGURATION.rst](src/doc/administration/configuration.rst)
6. Copy `conf/core/usersources.ini.template` to `conf/ext/usersources.ini`.
* You can skip this if you do not want to use an external authentication.
Local users (CaosDB realm) are always available.
diff --git a/lib/easy-units-0.0.1-SNAPSHOT-jar-with-dependencies.jar b/lib/easy-units-0.0.1-jar-with-dependencies.jar
similarity index 94%
rename from lib/easy-units-0.0.1-SNAPSHOT-jar-with-dependencies.jar
rename to lib/easy-units-0.0.1-jar-with-dependencies.jar
index c9bad485f59d2694cbcb64dee8b5242b2e4b0d72..325862a45f9bb338541e99c24ad1b8421577a61c 100644
Binary files a/lib/easy-units-0.0.1-SNAPSHOT-jar-with-dependencies.jar and b/lib/easy-units-0.0.1-jar-with-dependencies.jar differ
diff --git a/lib/easy-units-0.0.1-javadoc.jar b/lib/easy-units-0.0.1-javadoc.jar
new file mode 100644
index 0000000000000000000000000000000000000000..2785b00e4119fb201fb9a0a373c2dd2ac01ee701
Binary files /dev/null and b/lib/easy-units-0.0.1-javadoc.jar differ
diff --git a/lib/easy-units-0.0.1-sources.jar b/lib/easy-units-0.0.1-sources.jar
new file mode 100644
index 0000000000000000000000000000000000000000..83d50d59bad73ea067475d1cf247c8b31d82fb40
Binary files /dev/null and b/lib/easy-units-0.0.1-sources.jar differ
diff --git a/pom.xml b/pom.xml
index 7fece112f6b7bff37e0f8b8afdab0579e073a842..d2616a454bee0031285fa82b51bffdb97c53e4b1 100644
--- a/pom.xml
+++ b/pom.xml
@@ -52,7 +52,7 @@
<dependency>
<groupId>de.timmfitschen</groupId>
<artifactId>easy-units</artifactId>
- <version>0.0.1-SNAPSHOT</version>
+ <version>0.0.1</version>
</dependency>
<dependency>
<groupId>org.quartz-scheduler</groupId>
@@ -241,7 +241,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
- <version>3.0.0-M3</version>
+ <version>3.0.0-M5</version>
<configuration>
<includes>
<include>**/*.java</include>
diff --git a/src/doc/Makefile b/src/doc/Makefile
index 4f177fd3850423c3005829a75a2b37625dc68a87..1f0af46e75a27dc9ff8d124782fca27400e4a240 100644
--- a/src/doc/Makefile
+++ b/src/doc/Makefile
@@ -1,4 +1,3 @@
-# ** header v3.0
# This file is a part of the CaosDB Project.
#
# Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
@@ -16,8 +15,7 @@
#
# 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/>.
-#
-# ** end header
+
# This Makefile is a wrapper for sphinx scripts.
#
@@ -28,10 +26,15 @@
SPHINXOPTS ?= -a
SPHINXBUILD ?= sphinx-build
SPHINXAPIDOC ?= javasphinx-apidoc
+
+APIXMLDIR = development/api/xml/
SOURCEDIR = .
BUILDDIR = ../../build/doc
-.PHONY: doc-help Makefile apidoc
+# Don't make the documentation of the XML api at least until
+# https://github.com/OpenAPITools/openapi-generator/issues/9923 is
+# resolved
+.PHONY: doc-help Makefile apidoc # apixml
# Put it first so that "make" without argument is like "make help".
doc-help:
@@ -39,9 +42,12 @@ doc-help:
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile apidoc
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+%: Makefile apidoc # apixml
+ $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# sphinx-build -M html . ../../build/doc
apidoc:
- @$(SPHINXAPIDOC) -o _apidoc --update --title="CaosDB Server" ../main/
+ $(SPHINXAPIDOC) -o _apidoc --update --title="CaosDB Server" ../main/
+
+apixml:
+ $(MAKE) -C $(APIXMLDIR) doc
diff --git a/src/doc/administration/configuration.rst b/src/doc/administration/configuration.rst
index 196acb34ee9afbe6b35d530b058fac6c275299aa..c91ac16b1068b9261638aa697f3d11fd42a0d5cc 100644
--- a/src/doc/administration/configuration.rst
+++ b/src/doc/administration/configuration.rst
@@ -1,29 +1,43 @@
-Configuration
-=============
+Server Configuration
+====================
-The server is configured through configuration files. There are two directories with config files:
+Main Configuration File
+-----------------------
-``conf/core``
- Upstream defaults are stored here.
-``conf/ext``
- User specific configuration should be stored here, settings in ``ext`` override settings in
- ``core``. Additionally, configuration files may be stored in ``*.d`` directories here, named
- after the original config file name. For example, the general server configuration will be
- assembled from ``conf/core/server.conf``, ``conf/ext/server.conf`` and any ``*.conf`` files found
- in ``conf/ext/server.conf.d``.
+The server is configured through configuration files. The main file is the
+`server.conf`.
-Configuration files
--------------------
+The `server.conf` is a list of key-value pairs. A configuration file may
+contain empty lines, comment lines, and key-value lines. Comment lines begin
+with a hash (`#`). Key-value lines must have the format `KEY_NAME=VALUE` or
+`KEY_NAME = VALUE`.
-In each of these directories, the server looks for the following files:
-``server.conf``
- General server configuration options. The possible configuration options are documented inside
- the `default file
- <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/server.conf>`__.
+The server default configuration is located at `./conf/core/server.conf`.
+Upstream defaults are stored here. The possible configuration options are
+documented inside the
+`default file <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/server.conf>`__.
+
+User specific configuration should be in `./conf/ext/` and override settings
+in `./conf/core/`.
+
+The default configuration can be overriden by
+
+ 1. the file ./conf/ext/server.conf
+
+ 2. any file in ./conf/ext/server.conf.d/ in (approximately?) alphabetical order
+
+ 3. environment variables with the prefix `CAOSDB_CONFIG_`
+
+in this order.
+
+Further Configuration Files
+---------------------------
+
+Further settings are to be set in files which are by default stored in `./conf/core/`:
``global_entity_permissions.xml``
- :doc:`Permissions<../Permissions>` which are automatically set, based on user roles. See the
+ :doc:`Permissions<../permissions>` which are automatically set, based on user roles. See the
`default file
<https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/global_entity_permissions.xml>`__.
@@ -39,8 +53,10 @@ In each of these directories, the server looks for the following files:
``authtoken.yaml``
Configuration for dispensed authentication tokens, which can be used to authenticate to CaosDB
- without the need of a user/password combination. Possible use cases are server-side scripts or
- initial setup after the server start. There is more documentation inside the `template file
+ without the need of a user/password combination. One-time Authentication Tokens can be configure
+ to be issued for special purposes (e.g. a call of a server-side script or initial setup after the server start)
+ or to be written to a file on a regular basis. An example of a configuration is located at `./conf/core/authtoken.example.yaml`.
+ There is more documentation inside the `template file
<https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/authtoken.example.yaml>`__.
``cache.ccf``
@@ -54,6 +70,9 @@ In each of these directories, the server looks for the following files:
<https://logging.apache.org/log4j/2.x/>`_. The ``default`` file is always loaded, in debug mode
the ``debug`` file iss added as well.
+The administrator may set the corresponding options in the main configuration
+file (`./conf/core/server.conf` and it's friends) to replace these special
+files with custom configuration.
Changing the configuration at runtime
-------------------------------------
diff --git a/src/doc/development/api/xml/Makefile b/src/doc/development/api/xml/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..b2314adb191575895a89770332261b505543e0f3
--- /dev/null
+++ b/src/doc/development/api/xml/Makefile
@@ -0,0 +1,35 @@
+# 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.2.0/openapi-generator-cli-5.2.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)
diff --git a/src/doc/development/api/xml/caosdb_openapi.yaml b/src/doc/development/api/xml/caosdb_openapi.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..b2e0b7449d0ab9c4bc147692862aa69107828bac
--- /dev/null
+++ b/src/doc/development/api/xml/caosdb_openapi.yaml
@@ -0,0 +1,482 @@
+openapi: "3.0.3"
+info:
+ title: CaosDB XML REST API
+ description: The XML API of CaosDB, see also https://docs.indiscale.com/caosdb-server
+ version: 0.0-poc.1
+servers:
+ - url: https://demo.indiscale.com
+ description: Demo server, will reset its content from time to time.
+paths:
+ /Entity/{id}:
+ get:
+ operationId: getEntity
+ summary: Return an Entity with a given integer id.
+ description: This is the most direct way to return a single Entity.
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: The internal integer id of the entity to be retrieved.
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: The entity
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Response"
+ example:
+ username: admin
+ realm: PAM
+ srid: "some-srid"
+ timestamp: 12345
+ baseuri: "https://demo.indiscale.com"
+ count: 1
+ UserInfo:
+ username: admin
+ realm: PAM
+ Roles:
+ - administration
+ entity:
+ id: 146
+ name: "John Lennon's guitar"
+ Permissions:
+ - name: "RETRIEVE:ENTITY"
+ - name: "RETRIEVE:ACL"
+ Parent:
+ - name: Guitar
+ id: 110
+ Version:
+ id: "some-version-string"
+ head: true
+ Predecessor:
+ id: "some-old-version-string"
+ Property:
+ - name: electric
+ id: 106
+ datatype: "BOOLEAN"
+ value: "TRUE"
+ importance: FIX
+ Permissions:
+ - name: "RETRIEVE:ENTITY"
+ - name: "RETRIEVE:ACL"
+ delete:
+ operationId: deleteEntity
+ summary: Delete the entity with the given id
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: integer id of the entity to be deleted
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: The entity that was deleted
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Response"
+
+ /Entity/:
+ get:
+ operationId: executeQuery
+ summary: Return the entities matching the given query
+ description: Use arbitrary CaosDB queries to retrieve all matching entities
+ parameters:
+ - name: query
+ in: query
+ required: true
+ description: The actual query that is to be executed
+ schema:
+ type: string
+ - name: P
+ in: query
+ required: false
+ description: |
+ Start index within query results of the first entity and
+ total number of entities to be shown on one page,
+ separated by an 'L'
+ schema:
+ type: string
+ example: 0L10
+ pattern: "[0-9]+L[0-9]+"
+ responses:
+ '200':
+ description: "The query result"
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Response"
+ example:
+ UserInfo:
+ Roles:
+ - anonymous
+ Query:
+ string: "FIND RECORD"
+ results: 82
+ cached: true
+ etag: "some-etag-hash"
+ entity:
+ - name: "Result 1"
+ id: 101
+ - name: "Result 2"
+ id: 102
+ post:
+ operationId: insertEntity
+ summary: Insert one or more entities
+ description: Upload one or several entities to be inserted on the server
+ requestBody:
+ required: true
+ description: The entity or the entities to be inserted
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Request"
+ example:
+ entity:
+ - name: "MyNewRecord"
+ description: "Test"
+ Parent:
+ - name: "ParentType"
+ id: 123
+ Property:
+ - name: "SomeProperty"
+ id: 124
+ datatype: "INTEGER"
+ value: 3
+ responses:
+ '200':
+ description: The inserted entity object(s) with information added by the server
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Response"
+ example:
+ username: admin
+ realm: PAM
+ srid: "some-srid"
+ timestamp: 12345
+ baseuri: "https://demo.indiscale.com"
+ count: 1
+ UserInfo:
+ username: admin
+ realm: PAM
+ roles:
+ - administration
+ entity:
+ id: 365
+ name: "MyNewRecord"
+ description: "Test"
+ Version:
+ id: "some-version-string"
+ head: true
+ Permissions:
+ - name: "RETRIEVE:ENTITY"
+ - name: "RETRIEVE:ACL"
+ Parent:
+ - name: "ParentType"
+ id: 123
+ Property:
+ - name: "SomeProperty"
+ id: 124
+ datatype: "INTEGER"
+ value: 3
+ put:
+ operationId: updateEntity
+ summary: Update one or more entities
+ description: Attach one or several entities to be updated on the server
+ requestBody:
+ required: true
+ description: The entity or the entities to be updated
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Request"
+ example:
+ entity:
+ - name: "MyNewRecord"
+ id: 365
+ description: "Test"
+ Parent:
+ - name: "ParentType"
+ id: 123
+ Property:
+ - name: "SomeProperty"
+ id: 124
+ datatype: "INTEGER"
+ value: 3
+ - name: "SomeOtherProperty"
+ id: 125
+ datatype: "String"
+ value: "Hello"
+ responses:
+ '200':
+ description: The updated entity object(s) with information added by the server
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Response"
+ example:
+ username: admin
+ realm: PAM
+ srid: "some-srid"
+ timestamp: 12346
+ baseuri: "https://demo.indiscale.com"
+ count: 1
+ UserInfo:
+ username: admin
+ realm: PAM
+ roles:
+ - administration
+ entity:
+ id: 365
+ name: "MyNewRecord"
+ description: "Test"
+ Version:
+ id: "some-new-version-string"
+ head: true
+ Predecessor:
+ id: "some-version-string"
+ Permissions:
+ - name: "RETRIEVE:ENTITY"
+ - name: "RETRIEVE:ACL"
+ Parent:
+ - name: "ParentType"
+ id: 123
+ Property:
+ - name: "SomeProperty"
+ id: 124
+ datatype: "INTEGER"
+ value: 3
+ - name: "SomeOtherProperty"
+ id: 125
+ datatype: "String"
+ value: "Hello"
+components:
+ schemas:
+ Response:
+ type: object
+ description: Server response containing metadata and the requested entity
+ properties:
+ UserInfo:
+ $ref: "#/components/schemas/UserInfo"
+ username:
+ $ref: "#/components/schemas/username"
+ realm:
+ $ref: "#/components/schemas/realm"
+ srid:
+ $ref: "#/components/schemas/srid"
+ timestamp:
+ $ref: "#/components/schemas/timestamp"
+ baseuri:
+ type: string
+ description: URI to which the request was sent
+ xml:
+ attribute: true
+ count:
+ type: integer
+ description: Number of entities contained in this response
+ xml:
+ attribute: true
+ entity:
+ type: array
+ items:
+ $ref: "#/components/schemas/entity"
+ Query:
+ $ref: "#/components/schemas/Query"
+ Request:
+ type: object
+ description: Request to be inserted or updated
+ properties:
+ entity:
+ type: array
+ items:
+ $ref: "#/components/schemas/entity"
+ entity:
+ type: object
+ properties:
+ id:
+ $ref: "#/components/schemas/id"
+ name:
+ $ref: "#/components/schemas/name"
+ description:
+ type: string
+ example: This is a measurement.
+ xml:
+ attribute: true
+ Permissions:
+ type: array
+ items:
+ $ref: "#/components/schemas/Permission"
+ xml:
+ wrapped: true
+ Property:
+ type: array
+ items:
+ $ref: "#/components/schemas/Property"
+ Parent:
+ type: array
+ items:
+ $ref: "#/components/schemas/Parent"
+ Version:
+ $ref: "#/components/schemas/Version"
+ xml:
+ name: 'xml-entity'
+ UserInfo:
+ type: object
+ description: Information about the user that submitted the request
+ properties:
+ Roles:
+ type: array
+ items:
+ $ref: "#/components/schemas/Role"
+ xml:
+ wrapped: true
+ username:
+ $ref: "#/components/schemas/username"
+ realm:
+ $ref: "#/components/schemas/realm"
+ Role:
+ type: object
+ properties:
+ text:
+ type: string
+ example: "anonymous"
+ xml:
+ name: Role
+ username:
+ type: string
+ example: admin
+ xml:
+ attribute: true
+ realm:
+ type: string
+ example: PAM
+ xml:
+ attribute: true
+ srid:
+ type: string
+ xml:
+ attribute: true
+ timestamp:
+ type: integer
+ xml:
+ attribute: true
+ id:
+ description: The integer id of this entity
+ type: integer
+ xml:
+ attribute: true
+ example: 3
+ name:
+ type: string
+ example: Measurement
+ xml:
+ attribute: true
+ Permission:
+ type: object
+ properties:
+ name:
+ type: string
+ example: "RETRIEVE:ENTITY"
+ xml:
+ attribute: true
+ xml:
+ name: Permission
+ importance:
+ type: string
+ description: Importance of this property
+ xml:
+ attribute: true
+
+ Property:
+ type: object
+ required:
+ - id
+ - datatype
+ - importance
+ properties:
+ datatype:
+ type: string
+ description: The CaosDB datatype of this property
+ example: BOOLEAN
+ xml:
+ attribute: true
+ id:
+ $ref: "#/components/schemas/id"
+ name:
+ $ref: "#/components/schemas/name"
+ importance:
+ $ref: "#/components/schemas/importance"
+ Value:
+ type: array
+ items:
+ type: string
+ unit:
+ type: string
+ xml:
+ attribute: true
+ Permissions:
+ type: array
+ items:
+ $ref: "#/components/schemas/Permission"
+ xml:
+ wrapped: true
+
+ Parent:
+ type: object
+ properties:
+ id:
+ $ref: "#/components/schemas/id"
+ name:
+ $ref: "#/components/schemas/name"
+
+ Version:
+ type: object
+ properties:
+ id:
+ type: string
+ xml:
+ attribute: true
+ head:
+ type: boolean
+ xml:
+ attribute: true
+ Predecessor:
+ type: object
+ properties:
+ id:
+ type: string
+ xml:
+ attribute: true
+ Successor:
+ type: object
+ properties:
+ id:
+ type: string
+ xml:
+ attribute: true
+
+ Query:
+ type: object
+ properties:
+ string:
+ type: string
+ xml:
+ attribute: true
+ results:
+ type: integer
+ xml:
+ attribute: true
+ cached:
+ type: boolean
+ xml:
+ attribute: true
+ etag:
+ type: string
+ xml:
+ attribute: true
+ # TODO: Add remaining query properties. Also add POV Filter?
+
diff --git a/src/doc/development/api/xml/openapi_config.json b/src/doc/development/api/xml/openapi_config.json
new file mode 100644
index 0000000000000000000000000000000000000000..f27abea7e89a96ba0b39aa0f1ee5f3fdc836c854
--- /dev/null
+++ b/src/doc/development/api/xml/openapi_config.json
@@ -0,0 +1,8 @@
+{
+ "appName": "CaosDB",
+ "appDescription": "CaosDB, the open data management toolkit",
+ "infoUrl": "https://docs.indiscale.com/caosdb-server",
+ "infoEmail": "info@indiscale.com",
+ "licenseInfo": "License: AGPLv3",
+ "licenseUrl": "https://gitlab.com/caosdb/caosdb-server/-/blob/dev/LICENSE.md"
+}
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 2ae00f7e685407325903159257d6561912f94a66..21fd891c083e7932d8b342d93992b2d02158364e 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -19,8 +19,10 @@ Welcome to caosdb-server's documentation!
Welcome to the CaosDB, the flexible semantic data management toolkit!
-This documentation helps you to :doc:`get started<README_SETUP>`, explains the most important
-:doc:`concepts<concepts>` and has information if you want to :doc:`develop<development/devel>` CaosDB yourself.
+This documentation helps you to :doc:`get started<README_SETUP>`,
+explains the most important :doc:`concepts<concepts>` and has
+information if you want to :doc:`develop<development/devel>` CaosDB
+yourself.
Indices and tables
diff --git a/src/doc/roles.md b/src/doc/roles.md
index 5f4641b7a6f6fcb1b63cdd26edb706af117ee7d6..2d1d36c47c34658a306384e39033f7ea4e5eb040 100644
--- a/src/doc/roles.md
+++ b/src/doc/roles.md
@@ -10,7 +10,7 @@ users may have the same role, and there may be roles without any users.
The user and their roles are always returned by the server in answers to requests
and can thus be interpreted and used by clients. The most important use though
-is [permission](Permissions) checking in the server: Access and
+is [permission](doc:`permissions`) checking in the server: Access and
modification of
entities can be controlled via roles, so that users of a given role are allowed
or denied certain actions. Incidentally, the permission to edit the permissions
@@ -32,4 +32,4 @@ There are some special roles, which are automatically assigned to users:
Except for the `anonymous` role, these special roles are not returned by the
server, but can nevertheless be used to define
-[permissions](Permissions).
+[permissions](doc:`permissions`).
diff --git a/src/doc/specification/Specification-of-the-Entity-API.md b/src/doc/specification/Entity_Overview.md
similarity index 95%
rename from src/doc/specification/Specification-of-the-Entity-API.md
rename to src/doc/specification/Entity_Overview.md
index 5ef05b7898d40e43f320c9e3519a6d9520efffcd..ca197e50050d9ba2c593973148627c4d56708a67 100644
--- a/src/doc/specification/Specification-of-the-Entity-API.md
+++ b/src/doc/specification/Entity_Overview.md
@@ -1,6 +1,6 @@
-# Specification of the Entity API
+# Overview of the CaosDB Entities' structure
-**Warning:** This specification is outdated. It is included to serve as a starting point for a more up-to-date description of the entity API.
+**Warning:** This overview may be outdated.
Version: 0.1.0r1
diff --git a/src/doc/specification/entity_api.rst b/src/doc/specification/entity_api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3f6bdbcf700aaeebbe7d49fe79ac47c4ad4303ad
--- /dev/null
+++ b/src/doc/specification/entity_api.rst
@@ -0,0 +1,24 @@
+The Entity API
+==============
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+ :hidden:
+
+ Overview of the CaosDB Entities' structure<Entity_Overview>
+
+.. note::
+
+ Until the corresponding `bug of openapi-codegen <https://github.com/OpenAPITools/openapi-generator/issues/9923>`_
+ is resolved, the documentation of the OpenAPI specification of the
+ entity API is best rendered by gitlab.
+
+The details of the specification, including interactive examples, can
+be found `here
+<https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/tree/dev/src/doc/development/api/xml/caosdb_openapi.yaml>`_.
+Note that some commands may require authentication, which can be done with
+an authentication cookie as described in the :doc:`api
+documentation<Authentication>`. Specialities of the :doc:`scripting
+api<Server-side-scripting>` and the :doc:`file api<Fileserver>` are
+explained in the corresponding sections of the specifications.
diff --git a/src/doc/specification/index.rst b/src/doc/specification/index.rst
index 3609aa4a8eb6165adf6070faae26bfb8bd4ba50f..69677277fc793d513aa21f506295567340d462e1 100644
--- a/src/doc/specification/index.rst
+++ b/src/doc/specification/index.rst
@@ -1,20 +1,18 @@
-
Specification
=============
-
-.. toctree::
- :maxdepth: 2
- :caption: Contents:
- :hidden:
-
- AbstractProperty
- Fileserver
- Record
- Specification of the Entity API <Specification-of-the-Entity-API>
- Authentication
- Datatype
- Paging
- RecordType
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+ :hidden:
+
+ AbstractProperty
+ Fileserver
+ Record
+ Authentication
+ Datatype
+ Paging
+ RecordType
Server side scripting <Server-side-scripting>
Specification of the Message API <Specification-of-the-Message-API>
-
+ Specification of the Entity API <entity_api>