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.jsNote: if you want to transform OData V3, V4, or V4.01 into OpenAPI 3.0.x or 3.1.0, you better use the pure Node.js-based tool.
This script transforms one or more OData CSDL ($metadata) XML documents into OpenAPI JSON documents.
Install a Java SE JDK and make sure it is in the PATH
java -version
Clone or download this repository, go to the tools folder and type
npm install
To install globally type
npm install -g
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 CommandThis script transforms a single OData CSDL ($metadata) XML documents into OpenAPI 3.0.0 JSON documents.
The prerequisites are listed within transform.cmd:
In the tools folder execute
npm install
Then
transform path/to/XML-file
Depending on your use case you may want to write your own wrapper script and do some pre- or post-processing. In that case you just need Java installed, and can call the XSL transformations directly.
Make sure to add xalan/xalan.jar and xalan/serializer.jar to your CLASSPATH or add a -cp ... command-line argument to the examples below. Note that the separator character for the class path depends on the operating system, ; for Windows, : for Linux, …
If you don’t know up-front which of your input files is OData V2, and which is OData V4, use the detection script and capture its output:
java org.apache.xalan.xslt.Process -XSL path-to-tools/OData-Version.xsl -IN your-file
An OData V2 or V3 file needs to be converted to a temporary file in V4 format first:
java org.apache.xalan.xslt.Process -L -XSL path-to-tools/V2-to-V4-CSDL.xsl -IN your-file -OUT your-temp-V4-file
An OData V4 file can then be converted to OpenAPI 3.0.0 (change the values of parameters scheme, host, basePath, and odata-version to the correct values for your API):
java org.apache.xalan.xslt.Process -L -XSL path-to-tools/V4-CSDL-to-OpenAPI.xsl -PARAM scheme http -PARAM host your-host.com -PARAM basePath /url-path/of/your/service -PARAM odata-version 4.01 -PARAM openapi-version 3.0.0 -IN your-V4-file -OUT your-openapi-file.json
Check the <xsl:param name="..." /> elements in V4-CSDL-to-OpenAPI.xsl for further parameters that you might want to supply via -PARAM x y.
The mapping can be fine-tuned via annotations in the CSDL ($metadata) XML documents.