tools

XSLT-Based Tools

Tools for transforming OData CSDL ($metadata) XML documents into OpenAPI documents.

The core ingredient is the V4-CSDL-to-OpenAPI.xsl transformation. It transforms OData CSDL XML Version 4.0 documents into either OpenAPI 3.0.0 or Swagger 2.0 documents.

OData CSDL XML documents conforming to one of the predecessor OData versions 2.0 or 3.0 can be transformed into OData 4.0 with the V2-to-V4-CSDL.xsl transformation.

The two files transform.js and transform.cmd are wrapper scripts for Node.js and Windows Command.

The mapping can be fine-tuned via annotations in the CSDL ($metadata) XML documents.

transform.js for Node.js

Note: if you want to transform OData V3, V4, or V4.01 into OpenAPI 3.0.x, you better use the pure Node.js-based tool.

This script transforms one or more OData CSDL ($metadata) XML documents into OpenAPI JSON documents.

It uses xslt4node, which in turn needs node-gyp and a Java SE JDK.

Installation

Install a Java SE JDK and make sure it is in the PATH

javac -version

Install node-gyp globally, following the platform-specific installation instructions for node-gyp.

Clone or download this repository, go to the tools folder and type

npm install

To install globally type

npm install -g

Usage

Assuming you installed the script globally and your metadata file is MyMetadata.xml, then

odata-openapi -dp MyMetadata.xml

will transform it into MyMetadata.openapi.json with a nice yUML diagram and pretty-printed JSON.

Just type

odata-openapi -h

to get usage hints

Usage: odata-openapi <options> <source files>
Options:
 --basePath              base path (default: /service-root)
 -d, --diagram           include YUML diagram
 -h, --help              show this info
 --host                  host (default: localhost)
 -o, --openapi-version   3.0.0 or 2.0 (default: 3.0.0)
 -p, --pretty            pretty-print JSON result
 -r, --references        include references to other files
 --scheme                scheme (default: http)
 -t, --target            target file (only useful with a single source file)
 -u, --used-schemas-only produce only schemas that are actually used in operation objects

If you installed the script locally, start it via

node path_to_tools/transform.js ...

(replace path_to_tools with your local installation path).

transform.cmd for Windows Command

This script transforms a single OData CSDL ($metadata) XML documents into OpenAPI 3.0.0 JSON documents.

Installation

The prerequisites are listed within transform.cmd. It's quite a lot:

• Java SE 8 is installed and in the PATH
• git is installed and in the PATH
• Xalan is installed and CLASSPATH contains xalan.jar and serializer.jar
• YAJL's json_reformat has been compiled and is in the PATH
• Node.js is installed
• ajv-cli is installed
• https://github.com/OAI/OpenAPI-Specification is cloned next to this project

Usage

In the tools folder execute

transform

Supported Annotations

The mapping can be fine-tuned via annotations in the CSDL ($metadata) XML documents.