OAD [ōd]

Parse, validate and convert OpenAPI Definitions in exist-db.

This is a wrapper around the Swagger-Parser library.

Installation

Built packages of OAD are available on GitHub releases and the public package repository.

You can visit one of the pages, download the XAR and then install it in your exist-db instance using the package manager. Alternatively, you can run the xst command below.

xst packages install from-registry oad

NOTE: This XAR comes with addtional JAR files that need to be available at runtime. It is safer to restart the database after installation - or upgrade - in order to make sure that the classpath was updated.

Usage

Try

import module namespace oad="//eeditiones.org/ns/oad";

oad:report('https://petstore3.swagger.io/api/v3/openapi.json')

All module functions assume you have a API specification stored in exist or available via HTTP. The spec can be YAML or JSON. It allows to work with internal and external references.

In order for the Swagger-parser to be able to resolve external, relative references all of them need to be public.

If $uri is a DB-path (with or without xmldb:) it will be converted to a REST-lookup first. This means the REST endpoint must be accessible.

Example

If you have a specification stored in /db/apps/myapp/api.json

{
  "openapi" : "3.0.2",
  "info" : { "title" : "my specification", "version": "1.0.0" },
  "paths" : {
    "/find" : {
      "get" : {
        "responses" : {
          "200" : {
            "description" : "result",
            "content" : {
              "text/plain" : {
                "schema" : {
                  "type" : "string"
                }
              }
            }
          }
        }
      }
    }
  }
}

Then

import module namespace oad="//eeditiones.org/ns/oad";

oad:report('/db/apps/myapp/api.json')

will return

<info>
    <title>my specification</title>
    <description/>
    <version>1.0.0</version>
    <servers>
        <server url="/"/>
    </servers>
</info>

and

import module namespace oad="//eeditiones.org/ns/oad";

oad:validate('/db/apps/myapp/api.json')

yields

true()

Functions

oad:validate($uri as xs:string) as xs:boolean

Returns true() if the API definition is valid, false() otherwise (use oad:report to see the list of issues found).

oad:report($uri as xs:string) as document()

Inspect the given definition and summarize the information into an XML document with an info-element at its root. If the parser encounters issues these are listed as separate error-elements under errors.

oad:flatten($uri as xs:string) as xs:string

Flatten will inspect the given definition and extract schemas, parameters and such into components. They are then replaced by references.

oad:resolve($uri as xs:string) as xs:string

Resolves both internal and external references in an API definition. This will allow you to use it with Roaster, for example.

oad:convert($uri as xs:string, map(xs:string, *)) as xs:string

The swiss-army knife of the available functions. Can convert definitions from one format to the other (JSON to YAML/ YAML to JSON) while also allowing you to either resolve or flatten the definition.

The available options are listed in the table below:

option	description	allowed values	default
format	serialization format	"json", "yaml"	"json"
method	what to do with references?	"flatten", "resolve""	none

Build

• Requirements
  • Java 17 or later (the Gradle wrapper is included, no separate Gradle installation needed)

./gradlew build

will run the tests and create a oad-<version>.xar file in the folder build/libs.

oad requires eXist-db 7 and is built and tested against the latest development version of eXist-db (7.0.0-SNAPSHOT). Use version 1 of oad for eXist-db 6.

eXist-db snapshots are only published to GitHub Packages, which needs a GitHub token with read:packages, either in GITHUB_TOKEN or as gpr.token in ~/.gradle/gradle.properties.

Tests

Both the XQSuite tests and the JUnit tests in src/test/java run on the JUnit Platform against an embedded eXist-db as part of the build. The XQSuite tests are run by eXist-db's XQSuite engine, XQSuiteTest points it at the test files. To only run the tests, use

./gradlew test
./gradlew test --tests org.eeditiones.oad.DbResolverTest  # a single test class

The embedded database is configured in conf.xml, which also registers the oad module. Some tests read API definitions from petstore3.swagger.io and need network access.

Release

Releases are created by the CI workflow when a tag v<version> is pushed.

• Update the version in gradle.properties
• commit, tag (v<version>) and push the commit and the tag
• CI builds the XAR, runs the tests, checks that the XAR can be installed and creates a GitHub release with the XAR attached

The tag has to match the version in gradle.properties, otherwise no release is created.

Sponsors

This package was made possible thanks to the contributions from following institutions