OpenAPI

OpenAPI (formerly swagger) is a standard for REST-API documentation and so optimized to describe standardized communication with HTTP.

RESTXQ

RESTXQ is the implementation of well-known function annotations in XQuery.

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 annotations and uses xqDocs for describing the API.

It is meant to be used for a single expath package and written for eXist-db.

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:

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.

ant test && bash test/eXist-db-*/bin/startup.sh

Behind the curtain the information will be collected by calling

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 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.

Thank You, Open Source!