Initial commit

initial commit

add logo

add some major funcionality

add a test module

embed swagger-ui

minor

improvements

proceedings

proceedings

test on full example

update spdx

incl. Beerware

typo

reduce the full sample

.gitignore

+build/
+node_modules/
+test/
+expath-pkg.xml
+index.html

.gitlab-ci.yml

+image: docker.gitlab.gwdg.de/subugoe/openapi4restxq:latest
+
+stages:
+  - build
+  - test
+  - deploy
+
+build-develop:
+  except:
+      - master
+      - tags
+  stage: build
+  script:
+    - ant test
+  artifacts:
+    paths:
+      - build/*.xar
+      - test/
+
+build-master:
+  only:
+      - master
+  stage: build
+  script:
+    - cp master.build.properties local.build.properties
+    - ant test
+  artifacts:
+    paths:
+      - build/*.xar
+      - test/
+
+installation:
+  except:
+      - tags
+  stage: test
+  script:
+    - bash test/eXist-db-*/bin/startup.sh | tee output.log &
+    # wait for eXist
+    - while [ $(curl --head --silent http://localhost:8080 | grep -c "200 OK") == 0 ]; do sleep 2s; done
+    # shutdown eXist
+    - bash test/eXist-db-*/bin/shutdown.sh
+    - ls -al /tmp; mv /tmp/tests-* . || true
+  artifacts:
+    paths:
+      - output.log
+      - test/tests-*.xml
+      - test/eXist-db-*/webapp/WEB-INF/logs/expath-repo.log
+    reports:
+        junit: test/tests-*.xml
+
+upload:
+  only:
+      - master
+      - develop
+  except:
+      - tags
+  stage: deploy
+  script:
+    - FILENAME=$(ls build/*.xar)
+    - curl -u ci:${EXIST_UPLOAD_PW} -X POST -F file=@${FILENAME} https://ci.de.dariah.eu/exist-upload

CHANGELOG.md

+Please find the detailed changelog at [repo.xml](repo.xml).

Dockerfile

+FROM ubuntu:bionic-20190204
+
+RUN apt-get update && apt-get upgrade -yy && apt-get install curl lsb-release gnupg -y
+RUN curl https://deb.nodesource.com/setup_11.x | bash -
+RUN apt-get install -y nodejs ant

LICENSE

+GNU LESSER GENERAL PUBLIC LICENSE
+    Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+"The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+a) under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+b) under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+a) Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+a) Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+c) For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+d) Do one of the following:
+
+0) Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+
+1) Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that (a) uses at run time
+a copy of the Library already present on the user's computer
+system, and (b) will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+e) Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option 4d0, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option 4d1, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+5. Combined Libraries.
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+a) Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+
+b) Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

README.md

+# OpenAPI
+OpenAPI (formerly swagger) is a standard for REST-API documentation and so
+optimized to describe standardized communication with HTTP.
+
+# RESTXQ
+[RESTXQ](http://exquery.github.io/exquery/exquery-restxq-specification/restxq-1.0-specification.html)
+is the implementation of well-known function annotations in [XQuery](https://www.w3.org/TR/xquery-31/).
+
+# OpenAPI for RESTXQ
+This software combines the power of function annotation in XQuery to prepare an
+OpenAPI conform documentation. It covers the RESTXQ annotations as well as the
+[XQSuite](http://exist-db.org/exist/apps/doc/xqsuite.xml) annotations and uses
+[xqDocs](http://xqdoc.org/xqdoc_comments_doc.html) for describing the API.
+
+It is meant to be used for a single [expath package](http://expath.org/spec/pkg)
+and written for [eXist-db](http://exist-db.org).
+
+## Build
+For preparing the `openapi.json` the application is build with
+```
+ant
+```
+
+If you want to use swagger-ui (a ready-to-use documentation in HTML) you have to
+load the swagger-ui package before:
+```bash
+npm install && ant
+```
+
+## Install
+Install the build target (xar package) to a recent eXist-db by either placing
+the file in the `autodeploy` directory or using the package manager application
+installed by default at a running database.
+
+## Use
+The package provides a
+
+## Configure
+
+## Develop
+To start developing or testing the package a ant target is available that sets
+up the environment.
+```bash
+ant test && bash test/eXist-db-*/bin/startup.sh
+```
+
+Behind the curtain the information will be collected by calling
+```xq
+inspect:inspect-module(xs:anyURI("/db/apps/openapi/content/openapi-tests-full.xqm"))
+```
+
+
+## Limitations
+### combining path and query parameters
+Query parameters passed by `%rest:query-param()` MUST use a name different from
+path parameter variable names. Since the parameter name can be defined different
+from the variable name via this function, it is REQUIRED to use different path
+variable name and query parameter names. It is CONSIDERED to be best practice
+that both – name and var name – SHOULD not interfere or have any cross-realation
+by their names.
+
+### Example values
+Example values are taken from the `%test:arg()` annotation and the usage of
+`%test:args()` is not supported.
+
+# Credits
+There is no relation between the author of this software and the named companies,
+initiatives, products, specifications and trademarks.
+
+This software is written to comply with the OpenAPI Specifications (OAS) and
+provides an implementation for RESTXQ. It is tested with eXist-db eXclusively.
+
+Usage of the [OpenAPI Logo](icon.png) is in accordance to the guidelines
+provided at [openapis.org/faq](https://www.openapis.org/faq). In this case it is
+used to appear on eXist-db dashboard screen when this application is installed.
+
+OAS and OpenAPI Specification and their respective logos, are trademarks of The
+Linux Foundation. Linux is a registered trademark of Linus Torvalds.
+
+# Thank You, Open Source!

build.properties

+project.name=https://lab.sub.uni-goettingen.de/restxqopenapi
+project.version=1.0.0
+project.title=OpenAPI for RESTXQ
+project.abbrev=openapi-develop
+project.processorversion=4.6.0
+
+destfile=${build.dir}/${project.abbrev}-${project.version}.xar
+test.dir=test

build.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<project default="xar" name="openapi4restxq">
+
+  <property name="build.dir" value="build"/>
+  <property file="local.build.properties"/>
+  <property file="build.properties"/>
+
+  <antversion property="antversion"/>
+  <available file="node_modules/swagger-ui-dist" type="dir" property="swagger-ui-dist.present"/>
+  <target name="antversion-test">
+    <antversion property="antversionReady" atleast="1.10"/>
+    <fail unless="antversionReady">installed version of ant (${antversion}) is lower than the required one (1.10.0)</fail>
+    <echo message="installed version of ant (${antversion}) is satisfying"/>
+  </target>
+
+  <target name="xar" depends="cleanup, swagger-ui, spdx">
+      <copy file="expath-pkg.xml.tmpl" tofile="expath-pkg.xml" filtering="true" overwrite="true">
+          <filterset>
+              <filter token="project.version" value="${project.version}"/>
+              <filter token="project.title" value="${project.title}"/>
+              <filter token="project.abbrev" value="${project.abbrev}"/>
+              <filter token="project.name" value="${project.name}"/>
+              <filter token="project.processorversion" value="${project.processorversion}"/>
+          </filterset>
+      </copy>
+
+      <mkdir dir="${build.dir}"/>
+      <zip basedir="." destfile="${destfile}" defaultexcludes="no"
+          excludes=".git/,${build.dir}/,${test.dir}/,node_modules/"/>
+  </target>
+
+  <target name="swagger-ui-test" unless="swagger-ui-dist.present">
+    <echo level="warning">swagger-ui-dist is not available in ./node_modules.
+Run `npm install` first to build a package that includes swagger-ui.</echo>
+  </target>
+  <target name="swagger-ui" depends="swagger-ui-test" if="swagger-ui-dist.present">
+      <!-- swagger ui -->
+      <copy file="node_modules/swagger-ui-dist/favicon-16x16.png" tofile="resources/swagger/favicon-16x16.png" overwrite="true" />
+      <copy file="node_modules/swagger-ui-dist/favicon-32x32.png" tofile="resources/swagger/favicon-32x32.png" overwrite="true" />
+      <copy file="node_modules/swagger-ui-dist/swagger-ui.css" tofile="resources/swagger/swagger-ui.css" overwrite="true" />
+      <copy file="node_modules/swagger-ui-dist/swagger-ui-standalone-preset.js" tofile="resources/swagger/swagger-ui-standalone-preset.js" overwrite="true" />
+      <copy file="node_modules/swagger-ui-dist/swagger-ui-bundle.js" tofile="resources/swagger/swagger-ui-bundle.js" overwrite="true" />
+      <copy file="node_modules/swagger-ui-dist/index.html" tofile="index.html" overwrite="true" />
+      <replace file="index.html" token="&gt;Swagger UI&lt;" value="&gt;Swagger UI for ${project.title}&lt;"/>
+      <replace file="index.html" token=".css&quot; &lt;" value=".css&quot; /&lt;"/>
+      <replace file="index.html" token="UTF-8&quot;&lt;" value="UTF-8&quot;/&lt;"/>
+      <replaceregexp file="index.html" match="url:.*" replace=" url: 'openapi.json'," />
+      <replaceregexp file="index.html" match="(src|href)=&quot;\./" replace="\1=&quot;resources/swagger/" flags="g"/>
+  </target>
+
+  <target name="cleanup">
+    <delete dir="${test.dir}"/>
+  </target>
+
+  <target name="spdx">
+    <get src="https://spdx.org/licenses/licenses.json" dest="spdx-licenses.json"/>
+  </target>
+
+  <target name="test" depends="antversion-test, xar">
+    <!-- task setpermissions requries at least ant 1.10.0 -->
+    <get src="https://bintray.com/existdb/releases/download_file?file_path=eXist-db-${project.processorversion}.tar.bz2" dest="${build.dir}/eXist-db-${project.processorversion}.tar.bz2" skipexisting="true" />
+    <untar src="${build.dir}/eXist-db-${project.processorversion}.tar.bz2" dest="${test.dir}" compression="bzip2" />
+    <setpermissions mode="755">
+      <file file="${test.dir}/eXist-db-${project.processorversion}/bin/startup.sh"/>
+    </setpermissions>
+    <copy file="${destfile}" todir="${test.dir}/eXist-db-${project.processorversion}/autodeploy" />
+  </target>
+
+</project>

collection.xconf

+<?xml version="1.0" encoding="UTF-8"?>
+<collection xmlns="http://exist-db.org/collection-config/1.0">
+    <index xmlns:xs="http://www.w3.org/2001/XMLSchema">
+        <fulltext default="none" attributes="false"/>
+    </index>
+</collection>
\ No newline at end of file

content/openapi-tests-full.xqm

+(:~
+ : complex TESTMODULE for OpenAPI from RESTXQ.
+ : This is module number two.
+ : It provides more complex APIs.
+ :   :)
+xquery version "3.1";
+
+module namespace openapi-test-full="https://lab.sub.uni-goettingen.de/restxqopenapi/test2";
+
+declare namespace rest = "http://exquery.org/ns/restxq";
+declare namespace test="http://exist-db.org/xquery/xqsuite";
+declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
+
+
+(:~
+ : A more complex example with parameters in path and query in the request body.
+ : @param $paramPath A path paramter for your pleasure.
+ : @param $int Yet another path parametet. good.
+ : @param $format We specify the format by a classical file ending: preceded by a dot.
+ : @param $getParam Additional filter (string)
+ : @param $body an xml fragment to parse
+ : @return xml fragment that describes request and response
+ : @see http://example.com/documentation/about/this
+ :)
+declare
+%rest:POST("{$body}")
+%rest:consumes("application/xml", "text/xml")
+%rest:path("/openapi-test/full/post/{$paramPath}/{$int}.{$format}")
+%rest:query-param("getParam", "{$getParam}", "2019")
+
+%rest:produces("application/json")
+
+%output:method("json")
+
+%test:arg("paramPath", "here")
+%test:arg("int", "123")
+%test:arg("getParam", "and-get")
+function openapi-test-full:post(
+    $paramPath as xs:string,
+    $int as xs:int,
+    $format as xs:string,
+    $getParam as xs:string+,
+    $body as item()?)
+as element(test) {
+    <test>
+        <parameters n="6">
+            <path>{ $paramPath }</path>
+            <int>{ $int }</int>
+            <format>{ $format }</format>
+            <get1>{ $getParam }</get1>
+            <body>{ $body }</body>
+        </parameters>
+        <response n="1" type="application/json"/>
+    </test>
+};

content/openapi-tests-simple.xqm

+(:~
+ : TESTMODULE for OpenAPI from RESTXQ.
+ : This is number one.
+ :   :)
+xquery version "3.1";
+
+module namespace openapi-test-simple="https://lab.sub.uni-goettingen.de/restxqopenapi/test1";
+
+declare namespace rest = "http://exquery.org/ns/restxq";
+declare namespace test="http://exist-db.org/xquery/xqsuite";
+
+(:~
+ : Simple GET Method Test for OpenAPI
+ : @return xml fragment that describes request and response
+ : @see http://example.com/documentation/about/this
+ :)
+declare
+%rest:GET
+%rest:path("/openapi-test/simple/get")
+function openapi-test-simple:get()
+as element(test) {
+    <test>
+        <parameters n="0"/>
+        <response n="1" type="application/xml"/>
+    </test>
+};
+
+
+(:~
+ : Simple but deprecated GET Method Test for OpenAPI
+ : @return xml fragment that describes request and response
+ : @see http://example.com/documentation/about/this
+ : @deprecated
+ :)
+declare
+%rest:GET
+%rest:path("/openapi-test/simple/get-deprecated")
+function openapi-test-simple:get-deprecated()
+as element(test) {
+    <test>
+        <deprecated/>
+        <parameters n="0"/>
+        <response n="1" type="application/xml"/>
+    </test>
+};
+
+(:~
+ : Simple PUT Method Test for OpenAPI
+ : @return xml fragment that describes request and response
+ : @see http://example.com/documentation/about/this
+ :)
+declare
+%rest:PUT
+%rest:path("/openapi-test/simple/put")
+function openapi-test-simple:put()
+as element(test) {
+    <test>
+        <parameters n="0"/>
+        <response n="1" type="application/xml"/>
+    </test>
+};
+
+(:~
+ : Simple DELETE Method Test for OpenAPI
+ : @return xml fragment that describes request and response
+ : @see http://example.com/documentation/about/this
+ :)
+declare
+%rest:DELETE
+%rest:path("/openapi-test/simple/del")
+function openapi-test-simple:del()
+as element(test) {
+    <test>
+        <parameters n="0"/>
+        <response n="1" type="application/xml"/>
+    </test>
+};
+
+(:~
+ : Simple DELETE Method Test for OpenAPI
+ : @return xml fragment that describes request and response
+ : @see http://example.com/documentation/about/this
+ :)
+declare
+%rest:POST
+%rest:path("/openapi-test/simple/post")
+function openapi-test-simple:post()
+as element(test) {
+    <test>
+        <parameters n="0"/>
+        <response n="1" type="application/xml"/>
+    </test>
+};
+
+(:~
+ : Simple HEAD Method Test for OpenAPI
+ : @return empty as defined by HTTP
+ : @see http://example.com/documentation/about/this
+ :)
+declare
+%rest:HEAD
+%rest:path("/openapi-test/simple/head")
+function openapi-test-simple:head()
+as empty-sequence() {()};

content/openapi.xqm

+xquery version "3.1";
+(:~
+ : This library provides functions to prepare an OpenAPI description file for
+ : documenting public REST-APIs made with RESTXQ. Its output is a JSON file that
+ : can be used with swagger-ui.
+ : @author Mathias Göbel, SUB Göttingen
+ : @version 1.0
+ : @see https://www.openapis.org/
+ :)
+
+module namespace openapi="https://lab.sub.uni-goettingen.de/restxqopenapi";
+
+declare namespace rest="http://exquery.org/ns/restxq";
+declare namespace pkg="http://expath.org/ns/pkg";
+declare namespace repo="http://exist-db.org/xquery/repo";
+
+declare variable $openapi:supported-methods := ("rest:GET", "rest:HEAD", "rest:POST", "rest:PUT", "rest:DELETE");
+
+(:~
+ : Prepares a JSON document usually to be stored as "openapi.json".
+ : @param $target the collection to prepare the descriptor for, e.g. “/db/apps/application”
+ :   :)
+declare function openapi:json($target as xs:string)
+as xs:string {
+  openapi:main($target)
+  => serialize(map{ "method": "json", "media-type": "application/json" })
+};
+
+(:~
+ : Prepare OpenAPI descriptor for an installed package specified by its path in
+ : the database.
+ : @param $target the collection to prepare the descriptor for, e.g. “/db/apps/application”
+ : @return complete OpenAPI description
+ :)
+declare function openapi:main($target as xs:string)
+as map(*) {
+  let $modules-uris := collection($target)[ends-with(base-uri(), ".xqm")]/base-uri()
+  let $module :=
+    for $module in $modules-uris
+    let $inspect := inspect:inspect-module($module)
+    where $inspect/function/annotation/string(@name) = $openapi:supported-methods
+    return
+        $inspect
+
+  let $config := doc($target || "/openapi-config.xml")/*
+  let $repo := doc($target || "/repo.xml")/*
+  let $expath := doc($target || "/expath-pkg.xml")/*
+  return
+    map:merge((
+    map{"openapi": "3.0.1"},
+    openapi:paths-object($module),
+    openapi:servers-object($config/openapi:servers),
+    openapi:info-object($expath, $repo, $config/openapi:info),
+    openapi:tags-object($module)
+    ))
+};
+
+(:~
+ : Prepare OAS3 Info Object
+ : @see https://swagger.io/specification/#infoObject
+ :)
+declare %private function openapi:info-object($expath as element(pkg:package), $repo as element(repo:meta), $config as element(openapi:info))
+as map(*) {
+  map{ "info":
+    map{
+      "title": string($expath/pkg:title),
+      "description": string($repo/repo:description),
+      "termsOfService": string($config/openapi:termsOfService),
+      "contact": openapi:contact-object($repo, $config/openapi:contact),
+      "license": openapi:license-object($repo),
+      "version": string($expath/@version)
+    }
+  }
+};
+
+(:~
+ : Prepare a OAS Contact Object
+ : @see https://swagger.io/specification/#contactObject
+ :)
+declare %private function openapi:contact-object($repo as element(), $config as element(openapi:contact))
+as map(*) {
+    map{
+        "name": string($repo/repo:author[1]),
+        "url": string($repo/repo:website[1]),
+        "email": string($config/openapi:email)
+        }
+};
+
+(:~
+ : Prepare a OAS License Object
+ : @see https://swagger.io/specification/#licenseObject
+ :)
+declare function openapi:license-object($repo as element(repo:meta))
+as map(*) {
+  let $licenseId := string($repo/repo:license)
+  let $url := (map:get(openapi:spdx($licenseId), "seeAlso")?*)[1]
+  return
+    map{
+      "name": $licenseId,
+      "url": $url,
+      "x-name-is-spdx": exists($url)
+      }
+};
+
+(:~
+ : Prepares a OAS3 Servers Object
+ : @see https://swagger.io/specification/#serverObject
+ :)
+declare function openapi:servers-object($config as element(openapi:servers))
+as map(*) {
+  map{
+      "servers":[
+        for $server in $config/openapi:server
+        return
+          map{
+            "url": string($server/@url),
+            "description": string($server)
+          }
+        ]
+  }
+};
+
+(:~
+ : Prepare OAS3 Paths Object.
+ : @see https://swagger.io/specification/#pathsObject
+ :)
+declare %private function openapi:paths-object($module as element(module)+)
+as map(*) {
+  map{
+    "paths":
+      map:merge((
+        $module/function[annotation/@name = "rest:path"] ! openapi:operation-object(.)
+      ))
+  }
+};
+
+(:~
+ : Prepare OAS3 Operation Object.
+ : @see https://swagger.io/specification/#operationObject
+ :)
+declare function openapi:operation-object($function as element(function))
+as map(*) {
+  let $desc := normalize-space($function/description)
+  let $see := normalize-space($function/see)
+  let $deprecated := $function/deprecated
+  let $tags := array { $function/@name => substring-before(":") }
+  return
+  map{
+    $function/annotation[@name = "rest:path"]/replace(value, "\{\$", "{") :
+    for $method in $function/annotation[@name = $openapi:supported-methods]/substring-after(lower-case(@name), "rest:")
+    return
+    map{
+      $method:
+      map:merge((
+        map{ "description": $desc},
+        map{ "tags": $tags},
+        $see[1] ! map{"externalDocs": $see ! map{
+          "url": .,
+          "description": "the official documentation by the maintainer or a thrid-party documentation"}},
+        $deprecated ! map{"deprecated": true()},
+        openapi:parameter-object($function),
+        openapi:responses-object($function)
+      ))
+    }
+  }
+};
+
+(:~
+ : Prepare OAS3 Response Object.
+ : @see https://swagger.io/specification/#responsesObject
+ :  :)
+declare function openapi:responses-object($function as element(function))
+as map(*){
+  map{
+    "responses":
+    map{
+      "200": map{
+        "description": string($function/returns),
+        "content": openapi:mediaType-object($function)
+      }
+    }
+ }
+};
+
+(:~
+ : Prepare OAS3 Parameter Object.
+ : @see https://swagger.io/specification/#mediaTypeObject
+ :  :)
+declare function openapi:parameter-object($function as element(function))
+as map(*) {
+    let $pathParameters :=
+        $function/annotation[@name = "rest:path"][1]
+            /tokenize(value, "\{")
+            [starts-with(., "$")]
+            ! (.
+                => substring-after("$")
+                => substring-before("}")
+            )
+    let $pathParametersMap :=
+        for $parameter in $pathParameters
+        let $name := replace($parameter, "\{|\$|\}", "")
+        let $argument := $function/argument[@var eq $name]
+        let $basics := map:merge((
+                    map{
+                        "name": $name,
+                        "in": "path",
+                        "required": true()},
+                        openapi:schema-object($argument)
+        ))
+        let $description := $function/argument[@var = $name]/text() ! map{ "description": .}
+        let $example := string($function/annotation[@name = "test:arg"][value[1] = $name]/value[2]) ! map{ "example": .}
+        return
+            map:merge(($basics, $description, $example))
+
+    let $queryParameters := $function/annotation[@name = "rest:query-param"]
+    let $queryParametersMap :=
+        for $parameter in $queryParameters
+        let $name := string($parameter/value[2]) => replace("\{|\$|\}", "")
+        let $argument := $function/argument[@var eq $name]
+        let $required := exists($parameter/value[3] and not(contains($argument/@cardinality, "zero")))
+        let $basics :=
+                map:merge((
+                    map{
+                        "name": $name,
+                        "in": "query",
+                        "required": $required
+                        },
+                        openapi:schema-object($argument)
+                    ))
+        let $description := $function/argument[@var = $name]/text() ! map{ "description": .}
+        let $pos := index-of(($function/argument/string(@var)), $name)
+        let $example := $function/annotation[@name = "test:args"][1]/value[$pos]/text() ! map{ "example": .}
+        return
+            map:merge(($basics, $description, $example))
+    return
+        map{
+          "parameters": array{
+              $pathParametersMap,
+              $queryParametersMap
+          }
+        }
+};
+
+(:~
+ : Prepare OAS3 Media Type Object.
+ : @see https://swagger.io/specification/#mediaTypeObject
+ :  :)
+declare function openapi:mediaType-object($function)
+as map(*) {
+  let $produces := (
+        string($function/annotation[@name="rest:produces"]),
+        string($function/annotation[@name="output:media-type"]),
+        string($function/annotation[@name="output:method"]/openapi:method-mediaType(string(.))),
+        "application/xml"
+      )
+  return
+    map{
+      $produces[. != ""][1]: openapi:schema-object($function/returns)
+    }
+};
+
+(:~
+ : Prepare OAS3 Schema Object.
+ : @param $returns A element from the inspect-module() function,
+ : either *:returns or *:argument
+ : @see https://swagger.io/specification/#mediaTypeObject
+ :  :)
+declare function openapi:schema-object($returns as element(*))
+as map(*) {
+  map{"schema":
+    map:merge((
+        map{
+          "type": "string",
+          "x-xml-type": string($returns/@type)
+        },
+        if(contains($returns/@cardinality, "zero")) then map{ "nullable": true() } else ()
+    ))
+  }
+};
+
+declare function openapi:tags-object($modules as element(module)+)
+as map(*) {
+  map{
+    "tags": array{
+        for $module in $modules
+        return
+            map{
+                "name": string($module/@prefix),
+                "description": normalize-space($module/description)
+            }
+        }
+  }
+};
+
+(:~
+ : Resolve an SPDX licenseId
+ : @param a valid SPDX license code
+ : @return a map with all SPDX data to the requested license
+ :)
+declare function openapi:spdx($licenseId as xs:string)
+as map(*) {
+let $collection-uri := /id("restxqopenapi")/base-uri()
+let $item :=
+ (($collection-uri || "/../spdx-licenses.json")
+  => json-doc())("licenses")?*[?licenseId = $licenseId]
+
+return
+    map:merge($item)
+};
+
+(:~
+ : Get a media type from a method call to XQuery Serialization
+ : @param $method One of the specified methods
+ : @see https://www.w3.org/TR/xslt-xquery-serialization/
+ :  :)
+declare function openapi:method-mediaType($method as xs:string?)
+as xs:string?{
+    switch ($method)
+        case "html" return "text/html"
+        case "text" return "text/plain"
+        case "xml" return "application/xml"
+        case "xhtml" return "application/xhtml+xml"
+        case "json" return "application/json"
+        (: case "adaptive" return () :)
+        default return ()
+};

controller.xql

+xquery version "3.1";
+
+declare variable $exist:path external;
+declare variable $exist:resource external;
+declare variable $exist:controller external;
+declare variable $exist:prefix external;
+declare variable $exist:root external;
+
+if ($exist:path eq '') then
+    <dispatch xmlns="http://exist.sourceforge.net/NS/exist">
+        <redirect url="{request:get-uri()}/"/>
+    </dispatch>
+
+else if ($exist:path eq "/") then
+    (: redirect root path to index.html :)
+    <dispatch xmlns="http://exist.sourceforge.net/NS/exist">
+        <redirect url="index.html"/>
+    </dispatch>
+
+else if($exist:path eq "/openapi.json" and $exist:resource eq "openapi.json") then
+    (: forward to openapi.xq :)
+    <dispatch xmlns="http://exist.sourceforge.net/NS/exist">
+        <forward url="openapi.xq" />
+    </dispatch>
+
+else
+    (: everything else is passed through :)
+    <dispatch xmlns="http://exist.sourceforge.net/NS/exist">
+        <cache-control cache="yes"/>
+    </dispatch>

expath-pkg.xml.tmpl

+<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://expath.org/ns/pkg"
+  name="@project.name@"
+  abbrev="@project.abbrev@"
+  version="@project.version@"
+  spec="1.0"
+  xml:id="restxqopenapi">
+  <title>@project.title@</title>
+  <dependency processor="http://exist-db.org" semver-min="@project.processorversion@"/>
+  <xquery>
+    <namespace>https://lab.sub.uni-goettingen.de/restxqopenapi</namespace>
+    <file>openapi.xqm</file>
+  </xquery>
+</package>

master.build.properties

+project.name=https://lab.sub.uni-goettingen.de/openapi4restxq-develop
+project.abbrev=openapi

openapi-config.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<config xmlns="https://lab.sub.uni-goettingen.de/restxqopenapi">
+  <info>
+  <termsOfService>https://example.com/terms-of-use</termsOfService>
+  <contact>
+      <email>info@example.com</email>
+  </contact>
+  </info>
+  <servers>
+    <server url="http://localhost:8080/exist/restxq">Local development server</server>
+  </servers>
+</config>

openapi.xq

+xquery version "3.1";
+
+(: when using the library in other module the location part («at») SHOULD be
+ommited as the library registers its namespace to eXist. :)
+import module namespace openapi="https://lab.sub.uni-goettingen.de/restxqopenapi"
+  at "content/openapi.xqm";
+
+(: prepare a json document on HTTP requests :)
+declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
+declare option output:method "json";
+declare option output:media-type "application/json";
+
+(: we register the REST interface :)
+let $prepare := xmldb:get-child-resources("/db/apps/openapi/content")[. != "openapi.xqm"]
+    ! exrest:register-module(xs:anyURI("/db/apps/openapi/content/" || .))
+
+return
+
+(: prepare OpenAPI as map(*) :)
+openapi:main("/db/apps/openapi")
+
+(: ("paths")("/openapi-test/full/get/{param1}/{param2}.{format}") :)

package-lock.json

+{
+  "requires": true,
+  "lockfileVersion": 1,
+  "dependencies": {
+    "swagger-ui-dist": {
+      "version": "3.20.8",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.20.8.tgz",
+      "integrity": "sha512-dAvW8CVqJXYVVf8i7sppkpEGxzmXEKMkCYhNseSBUmkhb9IzENNaz5qVRrNEeCbDKNdJlrSKiilZy6cSHKL+ug=="
+    }
+  }
+}

package.json

+{
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.gwdg.de/subugoe/opanapi4restxq"
+  },
+  "license": "LGPL-3.0-or-later",
+  "dependencies": {
+    "swagger-ui-dist": "^3.20.8"
+  }
+}