Parse, validate and convert OpenAPI Definitions in exist-db.
This is a wrapper around the Swagger-Parser library.
- Download a pre-built XAR from the releases
- Install the package in your exist-db instance
- Restart the database
- 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.
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()
Returns true() if the API definition is valid, false() otherwise (use oad:report
to see the list of issues found).
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.
Flatten will inspect the given definition and extract schemas, parameters and such into components. They are then replaced by references.
Resolves both internal and external references in an API definition. This will allow you to use it with Roaster, for example.
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 |
- Requirements
- Java 8
- Apache Maven 3.3+
mvn package
will create a oad-<version>.xar
file in the target/
sub-folder.
There are no unit tests that will be executed when building the project. The build package does include xqsuite tests which test the integration into exist-db works as intended.
You can call that as part of your development workflow by running
./run-integration-tests.sh
mvn release:prepare
mvn release:perform