OpenAPI (formerly swagger) is a standard for REST-API documentation and so optimized to describe standardized communication with HTTP.
RESTXQ is the implementation of well-known function annotations in XQuery.
This is a BaseX port of the original exist-db version.
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 annotations and uses xqDocs for describing the API. (Note that this does not mean XQSuite works in BaseX. That would need to be ported separately.)
You can use your own annotation namespace for :args, :assertEquals, :consumes and :produces if you see unwanted side effects. %test has no meaning out of the box for BaseX.
It is meant to be cloned into a webapp RESTXQ directory of a BaseX
setup. content/openapi.xqm is a self contained module that can be copied into your project's directory.
If you want to use swagger-ui (a ready-to-use documentation in HTML) you have to load the swagger-ui package before:
yarn installIf you have the contents of this repository in your RESTXQ path (webapp by default) you have access to
swagger-ui using the /openapi URL.
repo.xml
<?xml version="1.0" encoding="UTF-8"?>
<meta xmlns="http://exist-db.org/xquery/repo">
<description>Describe your project</description>
<author>Your Name</author>
<website>urn:yourprojects_website</website>
<status>development</status>
<license ref="https://spdx.org/licenses/">MIT</license>
<copyright>true</copyright>
<type>application</type>
<target>yourproject</target>
<changelog>
<change version="0.3.0">
<ul xmlns="http://www.w3.org/1999/xhtml">
<li class="feat">Features
<ul style="margin-left: 15px;">
<li>Changed sth.</li>
<li>Changed sth. else</li>
<li>Yet another change</li>
</ul>
</li>
</ul>
</change>
</changelog>
</meta>You need some info XML files:
expath-pkg.xml
<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://expath.org/ns/pkg"
name="urn:yourproject"
abbrev="yourproj"
version="0.3.0"
spec="1.0"
xml:id="yourprojid">
<title>Project title</title>
<dependency processor="http://basex.org" semver-min="9.2"/>
<xquery>
<namespace>urn:yourproject</namespace>
<file>yourmodule.xqm</file>
</xquery>
</package>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:8984/">Local development server</server>
<server url="https://example.com/">Production server</server>
</servers>
<tags>
<tag name="category1" method="exclusive">
You can sort your functions into categories using these tags here.
<function name="yourproj:func1"/>
<function name="yourproj:func2"/>
</tag>
<tag name="category" method="exclusive">
Another category
<function name="yourproj:func3"/>
</tag>
</tags>
<!-- if you have any authentication: httpBasic info generation is implemented at the moment: >
<components>
<securitySchemes>
<securityScheme name="httpBasic">
This service uses HTTP Basic authentication.
<type>http</type>
<scheme>basic</scheme>
</securityScheme>
</securitySchemes>
</components>
<security>
<SecurityRequirement name="httpBasic"/>
</security> <!- -->
</config>- You can either put the contents of this repository in your RESTXQ directory and have the swagger-ui ready
and load
openapi.xqmfromopenapi4restxq/content/openapi.xqm - or you copy
content/openapi.xqm,openapi-config.xmlandspdx-licenses.jsonfor example into3rd-party/openapi. These files represent the XQuery code and some default configuration needed.
You then add a invocation like this (adjust the at "3rd-party/content/openapi.xqm" if you don't copy openapi.xqm)
import module namespace openapi="https://lab.sub.uni-goettingen.de/restxqopenapi" at "3rd-party/content/openapi.xqm";
[...]
declare
%rest:path('/yourrestproject/openapi.json')
%rest:produces('application/json')
%output:media-type('application/json')
function yourrestproject:getOpenapiJSON() as item()+ {
openapi:json(file:base-dir())
};This makes a json representation of your annotated and documented API avaialable.
You can load this in swagger-ui if you type /yourrestproject/openapi.json into the default explore input box.
If you want to configure swagger-ui's start parameters have a look at the documentation.
For example to have just a predefined set of openapi specifications available try the following code in openapi4restxq/resources/swagger-ui-dist/index.html:
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
urls: [
{ url: "/yourrestproject/openapi.json", name: "my rest API"},
{ url: "https://petstore.swagger.io/v2/swagger.json", name: "petstore example API"}
],
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
// End Swagger UI call region
window.ui = ui
}By default the application provides a preview and a few simple REST paths as test interfaces. Open the application via the Dashboard or browse to http://localhost:8984/openapi/index.html.
Change the the input filed in the top bar to openapi.json.
To view the documentation for other packages, use the input filed in the top bar
to ask for a description file at openapi.json?target=Q:\BaseX9\webapp\myApplication\.
To include information not present in one of the parsed documents, the library
checks the availability of a resources named openapi-config.xml in the
root collection of the application where to create the description file for.
It is recommended to place a customized copy of the file provided with this
package.
To start developing or testing the package just change openapi.xqm
Behind the curtain the information will be collected by calling
inspect:module("/basex/webapp/yourproject/yourmodule.xqm")Note that inspect:module and its exist-db counterpart generate comapreable but
different XML.
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 are taken from the %test:arg() annotation and the usage of
%test:args() is not supported.
- swagger.io for swagger-ui
- Mathias Goebel for the exist-db version of this tool
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 is in accordance to the guidelines provided at 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.