isabella232 / openapi4restxq

Mirror of https://gitlab.gwdg.de/subugoe/openapi4restxq

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

Integrated in own applications

By adding the following lines to the controller.xql a path like /myApplication/openapi/index.html will become available. (The usage of the pipe operator requires XQuery version 3.1.)

else if (starts-with($exist:path, "/openapi/")) then
  <dispatch xmlns="http://exist.sourceforge.net/NS/exist">
    <forward
      url="/openapi/{ $exist:path => substring-after("/openapi/") => replace("json", "xq") }"
      method="get">
      <add-parameter name="target" value="{ substring-after($exist:root, "://") || $exist:controller }"/>
      <add-parameter name="register" value="false"/>
    </forward>
  </dispatch>

Standalone

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:8080/exist/apps/openapi/index.html.

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=/db/apps/myApplication. Optional the re-registration of functions to the RESTXQ engine is possible via an additional parameter: &register=true.

Configure

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.

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!