oasis-tcs / odata-openapi Goto Github PK

OASIS OData TC: Tools for producing API descriptions for OData services that adhere to the OpenAPI Specification

Home Page: https://oasis-tcs.github.io/odata-openapi/

License: Other

XSLT 51.84% Batchfile 0.58% JavaScript 47.50% PowerShell 0.08%

odata-openapi's Introduction

README

Members of the OASIS Open Data Protocol (OData) Technical Committee create and manage technical content in this TC GitHub repository ( https://github.com/oasis-tcs/odata-openapi ) as part of the TC's chartered work (i.e., the program of work and deliverables described in its charter).

OASIS TC GitHub repositories, as described in GitHub Repositories for OASIS TC Members' Chartered Work, are governed by the OASIS TC Process, IPR Policy, and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from OASIS Open Repositories, which are used for development of open source licensed content.

Description

The purpose of this repository is to support development of tools for producing OpenAPI descriptions for OData services.

Planned work items include:

convert OData CSDL JSON or OData CSDL XML to OpenAPI JSON
example XML files
example openapi.json files
example files for the live odata.org services

Contributions

As stated in this repository's CONTRIBUTING file, contributors to this repository are expected to be Members of the OASIS OData TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and participate in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the OASIS Feedback License.

Licensing

Please see the LICENSE file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the OData TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository LICENSE file.

Further Description of this Repository

The OData TC has published the OData to OpenAPI Mapping Version 1.0, a recommendation on how to create OpenAPI descriptions for OData services. This project contains two proof-of-concept implementations of that mapping, one using JavaScript, and one using XSLT.

The examples folder contains OpenAPI 3.0.2 descriptions that have been created from the XML $metadata documents of live and example OData services with these proof-of-concept implementations.

The entity-relationship diagrams visualizing the resource models of each service are generated on-the-fly with yUML.

OpenAPI descriptions for live example OData services at www.odata.org

OpenAPI descriptions for OData services that reference each other (cross-service references)

Contact

Please send questions or comments about OASIS TC GitHub repositories to the OASIS TC Administrator. For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the OData TC's home page.

odata-openapi's People

Contributors

Stargazers

Watchers

odata-openapi's Issues

$batch documentation

Will this eventually support documentation of the $batch endpoint?

I don't see it in the OData v4 docs but I believe it is still supported.
http://www.odata.org/documentation/odata-version-3-0/batch-processing/

how to use this repo to convert SAP OData service into Swagger 2.0

OData 4 produces invalid JSON

Using http://services.odata.org/TripPinRESTierService/(S(x4ntlpt0jotx2ttqxrzytzir))/$metadata
produces invalid JSON and fails using pretty print which could be an additional clue. I also found this true for my OData 4 metadata service
foo.zip

ENUM for $expand, $select, and $orderby is too restrictive

According to OAS 3

Enums
You can use the enum keyword to specify possible values of a request parameter or a model property.

I believe possible values means that the ENUM values are the only valid values.

Currently this schema is generated for $expand, $select, and $orderby

{
  "schema": {
    "type": "array",
    "uniqueItems": true,
    "items": {
      "type": "string",
      "enum": ["foo", "bar", "baz"]
    }
  }
}

I like to suggest this instead

{
  "schema": {
    "type": "array",
    "uniqueItems": true,
    "items": {
      "anyOf": [
        {
          "type": "string",
          "enum": ["foo", "bar", "baz"]
        },
        {
          "type": "string"
        }
      ]
    }
  }
}

This would allow tooling to suggest values while also accepting free form text.
I didn't reason about if using oneOf is more correct then anyOf.

OData Query option $search missing from parameters

I am generating the OpenAPI 3.0 specification from the edmx using the transform script. The resulting specification appears fine but cannot be parsed because it lacks the odata $search parameter in the parameters list.metadata.openapi.

editor.swagger.io gives

Semantic error at paths./Organizations({ID})/mobilePhoneNumbers.get.parameters.2.$ref
$refs must reference a valid location in the document
Jump to line 871
Semantic error at paths./Persons({ID})/mobilePhoneNumbers.get.parameters.2.$ref
$refs must reference a valid location in the document
Jump to line 1975
Semantic error at paths./SimpleCustomers({ID})/emails.get.parameters.2.$ref
$refs must reference a valid location in the document
Jump to line 2895
Semantic error at paths./SimpleCustomers({ID})/phoneNumbers.get.parameters.2.$ref
$refs must reference a valid location in the document
Jump to line 2985

metadata.xml.zip

Unable to transform Microsoft Graph APIs metadata

Hi,

I am trying to transform the following metadata with v4-csdl-to-open-api.xsl:
https://graph.microsoft.com/v1.0/$metadata

But I am getting error. Upon trying online with multiple tools, all throw different errors.

Regards,
Saurabh Jain

Deep insert and expanded entity

Currently in ODATA V2.0, we can create deep insert and expanded entity and correspondingly use POST method to post the data into SAP backend.
However when we try to use the transformation to generate OPENAPI spec for the API and publish it in Swagger, no POST methods are shown.
How can this be manipulated in the transformation?

npm install fails on Windows 10

I followed the installation instructions. Tried both opt1 and opt2 of node-gyp. Neither made a difference.

I have these set

npm config set python python2.7
npm config set msvs_version 2017

Log

PS C:\Repos\odata-openapi\tools> npm i

> [email protected] install C:\Repos\odata-openapi\tools\node_modules\java
> node-gyp rebuild

C:\Repos\odata-openapi\tools\node_modules\java>if not defined npm_config_node_gyp (node "C:\Users\ME\AppData\Roaming\npm\node_modules\npm\node_modules\npm-lifecycle\node-gyp-bin\\..\..\node_modules\node-gyp\bin\node-gyp.js" rebuild )  else (node "C:\Users\ME\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" rebuild )
Building the projects in this solution one at a time. To enable parallel build, please add the "/m" switch.
  java.cpp
  javaObject.cpp
  javaScope.cpp
  methodCallBaton.cpp
  nodeJavaBridge.cpp
c:\repos\odata-openapi\tools\node_modules\nan\nan_converters_43_inl.h(22): warning C4996: 'v8::Value::ToBoolean': was declared deprecated (compiling source file ..\src\java.cpp) [C:\Repos\odata-op
enapi\tools\node_modules\java\build\nodejavabridge_bindings.vcxproj]
  c:\users\me\.node-gyp\12.4.0\include\node\v8.h(2523): note: see declaration of 'v8::Value::ToBoolean' (compiling source file ..\src\java.cpp)
c:\repos\odata-openapi\tools\node_modules\nan\nan_converters_43_inl.h(22): warning C4996: 'v8::Value::ToBoolean': was declared deprecated (compiling source file ..\src\javaObject.cpp)c:\repos\odat
a-openapi\tools\node_modules\nan\nan_converters_43_inl.h(40): warning C4996: 'v8::Value::BooleanValue': was declared deprecated (compiling source file ..\src\java.cpp) [C:\Repos\odata-openapi\tools\node_modules\java\
build\nodejavabridge_bindings.vcxproj]

  c:\users\me\.node-gyp\12.4.0\include\node\v8.h(2523): note: see declaration of 'v8::Value::ToBoolean' (compiling source file ..\src\javaObject.cpp)c:\users\me\.node-gyp\12.4.0\include\node\v8.h(2561): note: see declaration of 'v8::V
  alue::BooleanValue' (compiling source file ..\src\java.cpp)

c:\repos\odata-openapi\tools\node_modules\nan\nan_converters_43_inl.h(40): warning C4996: 'v8::Value::BooleanValue': was declared deprecated (compiling source file ..\src\javaObject.cpp) [C:\Repos
\odata-openapi\tools\node_modules\java\build\nodejavabridge_bindings.vcxproj]
  c:\users\me\.node-gyp\12.4.0\include\node\v8.h(2561): note: see declaration of 'v8::Value::BooleanValue' (compiling source file ..\src\javaObject.cpp)
c:\repos\odata-openapi\tools\node_modules\nan\nan_implementation_12_inl.h(103): error C2664: 'v8::MaybeLocal<v8::Function> v8::Function::New(v8::Local<v8::Context>,v8::FunctionCallback,v8::Local<v8::Value>,int,v8::Co
nstructorBehavior,v8::SideEffectType)': cannot convert argument 1 from 'v8::Isolate *' to 'v8::Local<v8::Context>' (compiling source file ..\src\java.cpp) [C:\Repos\odata-openapi\tools\node_modules\java\build\nodejav
abridge_bindings.vcxproj]
  c:\repos\odata-openapi\tools\node_modules\nan\nan_implementation_12_inl.h(105): note: No constructor could take the source type, or constructor overload resolution was ambiguous (compiling source file ..\src\java.c
  pp)
c:\repos\odata-openapi\tools\node_modules\nan\nan_implementation_12_inl.h(103): error C2664: 'v8::MaybeLocal<v8::Function> v8::Function::New(v8::Local<v8::Context>,v8::FunctionCallback,v8::Local<v8::Value>,int,v8::Co
nstructorBehavior,v8::SideEffectType)': cannot convert argument 1 from 'v8::Isolate *' to 'v8::Local<v8::Context>' (compiling source file ..\src\javaObject.cpp) [C:\Repos\odata-openapi\tools\node_modules\java\build\n
odejavabridge_bindings.vcxproj]

A LOT MORE!

gyp ERR! build error
gyp ERR! stack Error: `C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\MSBuild\15.0\Bin\MSBuild.exe` failed with exit code: 1
gyp ERR! stack     at ChildProcess.onExit (C:\Users\ME\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\build.js:262:23)
gyp ERR! stack     at ChildProcess.emit (events.js:200:13)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:272:12)
gyp ERR! System Windows_NT 10.0.18362
gyp ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\ME\\AppData\\Roaming\\npm\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild"
gyp ERR! cwd C:\Users\ME\Documents\Repos\odata-openapi\tools\node_modules\java
gyp ERR! node -v v12.4.0
gyp ERR! node-gyp -v v3.8.0
gyp ERR! not ok
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] install: `node-gyp rebuild`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] install script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\ME\AppData\Roaming\npm-cache\_logs\2019-08-13T16_34_44_231Z-debug.log

Please help

Node v12.4.0
NPM v6.9.2
JAVA javac 1.8.0_211 (also tried openJDK12)
Python v2.7.16

Edm.Decimal gets to number and string

The following OData V2 property will be transformed in a wrong way:

<Property Name="gross_amount" Type="Edm.Decimal" Precision="16" Scale="3" sap:unit="currency_code" sap:label="Gross Amount" sap:heading="Total Gross Amount" sap:quickinfo="EPM: Total Gross Amount"/>

The result is

gross_amount":{"type":["number","string","null"],"format":"decimal","multipleOf":1.0e-3,"title":"Gross Amount","description":"EPM: Total Gross Amount"

IMHO it should become a number with nullable attribute.

running script with Python 3.6

I am trying to run npm install and I am getting following error

C:\Users\hitesh.arora\odata-openapi\tools\node_modules\java>if not defined npm_config_node_gyp (node "C:\Users\hitesh.arora\AppData\Roaming\npm\node_modules\npm\node_modules\npm-lifecycle\node-gyp-bin\....\node_modules\node-gyp\bin\node-gyp.js" rebuild ) else (node "C:\Users\hitesh.arora\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" rebuild )
gyp ERR! configure error
gyp ERR! stack Error: Command failed: C:\Users\hitesh.arora\AppData\Local\Programs\Python\Python36\python.exe -c import sys; print "%s.%s.%s" % sys.version_info[:3];
gyp ERR! stack File "", line 1
gyp ERR! stack import sys; print "%s.%s.%s" % sys.version_info[:3];
gyp ERR! stack ^
gyp ERR! stack SyntaxError: invalid syntax
gyp ERR! stack
gyp ERR! stack at ChildProcess.exithandler (child_process.js:294:12)
gyp ERR! stack at ChildProcess.emit (events.js:189:13)
gyp ERR! stack at maybeClose (internal/child_process.js:970:16)
gyp ERR! stack at Process.ChildProcess._handle.onexit (internal/child_process.js:259:5)
gyp ERR! System Windows_NT 10.0.17763
gyp ERR! command "C:\Program Files\nodejs\node.exe" "C:\Users\hitesh.arora\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" "rebuild"
gyp ERR! cwd C:\Users\hitesh.arora\odata-openapi\tools\node_modules\java
gyp ERR! node -v v10.15.3
gyp ERR! node-gyp -v v3.8.0
gyp ERR! not ok
npm WARN [email protected] license should be a valid SPDX license expression

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] install: node-gyp rebuild
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] install script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR! C:\Users\hitesh.arora\AppData\Roaming\npm-cache_logs\2019-05-23T13_35_37_487Z-debug.log

Is given scripts run for python 3.6?

Edm.DateTime is not converted into Edm.DateTimeOffset or Edm.Date

I have this property in my SAP CSDL v2

<Property Name="someDate" Type="Edm.DateTime" Precision="7" sap:unicode="false" sap:label="Some Date" sap:creatable="false" sap:updatable="false" sap:sortable="false" sap:filterable="false"/>

According to this the type should have been converted to Edm.DateTimeOffset or Edm.Date

odata-openapi/tools/V2-to-V4-CSDL.xsl

Line 14 in a7887d1

  The retired primitive type Edm.DateTime is translated into Edm.DateTimeOffset or Edm.Date. 

But after running odata-openapi odatav2.xml I get this

{
  "openapi": "3.0.0",
  // omitted
  "components": {
    "schemas": {
      "MY_NAMESPACE.FooBar": {
        "type": "object",
        "properties": {
          "someDate": {
            "type": "string",
            "nullable": true,
            "example": "/Date(1492098664000)/",
            "title": "Some Date"
          }
        }
      }
    }
  }
}

Am I doing something wrong? I'm assuming the tool automatically runs the v2 to v4 conversion.

npm install fails on windows 10

PS D:\git\github\odata-openapi\tools> npm install

[email protected] install D:\git\github\odata-openapi\tools\node_modules\java
node-gyp rebuild
D:\git\github\odata-openapi\tools\node_modules\java>if not defined npm_config_node_gyp (node "C:\Program Files\nodejs\node_modules\npm\node_modules\npm-lifecycle\node-gyp-bin\....\node_modules\node-gyp\bin\node-gyp.js" rebuild ) else (node "C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" rebuild )
Building the projects in this solution one at a time. To enable parallel build, please add the "/m" switch.
D:\git\github\odata-openapi\tools\node_modules\java\build\nodejavabridge_bindings.vcxproj(20,3): error MSB4019: The imp
orted project "D:\Microsoft.Cpp.Default.props" was not found. Confirm that the path in the declaration is corr
ect, and that the file exists on disk.
gyp ERR! build error
gyp ERR! stack Error: ``C:\Program Files (x86)\MSBuild\14.0\bin\msbuild.exe failed with exit code: 1 gyp ERR! stack at ChildProcess.onExit (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\build.js:262:23) gyp ERR! stack at ChildProcess.emit (events.js:189:13) gyp ERR! stack at Process.ChildProcess._handle.onexit (internal/child_process.js:248:12) gyp ERR! System Windows_NT 10.0.17134 gyp ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild" gyp ERR! cwd D:\git\github\odata-openapi\tools\node_modules\java gyp ERR! node -v v10.15.1 gyp ERR! node-gyp -v v3.8.0 gyp ERR! not ok npm WARN [email protected] license should be a valid SPDX license expression npm ERR! code ELIFECYCLE npm ERR! errno 1 npm ERR! [email protected] install: node-gyp rebuild npm ERR! Exit status 1 npm ERR! npm ERR! Failed at the [email protected] install script. npm ERR! This is probably not a problem with npm. There is likely additional logging output above. npm ERR! A complete log of this run can be found in: npm ERR! C:\Users\mhainc\AppData\Roaming\npm-cache\_logs\2019-02-22T08_18_19_767Z-debug.log PS D:\git\github\odata-openapi\tools>

Is Edmx schema support readonly properties or Entities

I try to read edmx schema to know if property is readonly, so I can generate property as:

           public string FullName {get;}      //readonly property

I didn't find readonly in Odata v4 standard

Is Odata standard provide specs for readonly properties or Entities?

Support for deep/nested $expand

While the documentation states that's it's too complex

Note: the syntax of the system query options $expand, $select, and $orderby is too flexible to be formally described with OpenAPI Specification means, yet the typical use cases of just providing a comma-separated list of properties can be expressed via an array-valued parameter with an enum constraint, as shown in the following example. This makes it easy to try out these system query options in OpenAPI tools.

I think a naive solution it possible. For example currently this is generated for $expand

{
  "name": "$expand",
  "in": "query",
  "description": "Expand related entities",
  "explode": false,
  "schema": {
    "type": "array",
    "uniqueItems": true,
    "items": {
      "type": "string",
      "enum": ["toFoos"]
    }
  }
}

But traversing the XML NavigationPropertys it could probably be turned into

"enum": ["toFoos", "toFoos/toBars", "toFoos/toBars/toBazs"]

PATCH generation instead of PUT for OData v4

This transformer generates PATCH operation instead of PUT for OData (v4.0) even though the backend service supports only PUT.

We have source OData (v2) which we convert to OData (v4) using the V2-to-V4-CSDL.xsl and then generate openAPI spec using V4-CSDL-to-OpenAPI.xsl. The generated openAPI spec has PATCH operation instead of PUT.

Can we have a transformer which generates "V2-CSDL-to-OpenAPI" that retains the operation as PUT instead of converting that to PATCH?

Is there any other way we can approach this problem?

The generated PATCH operation in OpenAPI spec is of no use as backend doesn't support PATCH.

Support of com.sap.vocabularies.Common.v1.ValueList annotation planned?

IMHO one of the biggest issue with OData services V2 are missing enumeration types. This makes interfaces very hard to use. Therefore I would like to ask, whether a support of the com.sap.vocabularies.Common.v1.ValueList annotation is planned. Maybe those values could be transformed to OData V4 enumeration type and exported as Open API enum.

Metadata first

Is there a tool for editing metadata xml files ? I would like to define metadata document first

Dependency sax-js doesn't support custom entities in xml

XML Entities are useful to express some repeated sets of annotations (like disabling support for all $* parameters on the endpoint) and just reference them. sax.js doesn't support those. Leonidas-from-XIV/node-xml2js#443
It makes sense to use another parser.

oData V2 to oData V4 / OpenAPI 3.0

Hello,

I generated a metadata document of a oData service defined in SAP. This document is oData v2.
Now I try to convert this file to a OpenAPI document to process further. The conversion from v2 to v3 should be done automatically as I thought and found in the coding of the transform files.

When trying with command "odata-openapi3", there is a error, that only oData v3 is supported, when trying "odata-openapi", there appears an error:

My .xml files begins with:

<edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:sap="http://www.sap.com/Protocols/SAPData">
<edmx:Reference Uri="http://:8000/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/Vocabularies(TechnicalName='%2FIWBEP%2FVOC_COMMON',Version='0001',SAP__Origin='LOCAL')/$value" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
<edmx:Include Namespace="com.sap.vocabularies.Common.v1" Alias="Common"/>
</edmx:Reference>
<edmx:DataServices m:DataServiceVersion="3.0">

Do you have any advice on how to proceed. Or do I do it the wrong way?

Thanks in advance for your help.
Greetings

is there a path definition for metadata and service document?

Hi,

Does OData OpenAPI mapping doc define the rules for metadata and service document path?

Thanks,
-Sam

gyp error in npm install

I am trying to install node modules in tools

'" KeyError: '2019'
gyp ERR! configure error
gyp ERR! stack Error: gyp failed with exit code: 1
gyp ERR! stack at ChildProcess.onCpExit (C:\Users\hitesh.arora\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\configure.js:345:16)
gyp ERR! stack at ChildProcess.emit (events.js:189:13)
gyp ERR! stack at Process.ChildProcess._handle.onexit (internal/child_process.js:248:12)
gyp ERR! System Windows_NT 10.0.17763
gyp ERR! command "C:\Program Files\nodejs\node.exe" "C:\Users\hitesh.arora\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" "rebuild"
gyp ERR! cwd C:\odata-openapi\tools\node_modules\java
gyp ERR! node -v v10.15.3
gyp ERR! node-gyp -v v3.8.0
gyp ERR! not ok
npm WARN [email protected] license should be a valid SPDX license expression

npm ERR! A complete log of this run can be found in:
npm ERR! C:\Users\hitesh.arora\AppData\Roaming\npm-cache_logs\2019-05-29T09_51_35_705Z-debug.log""

SAP OData missing __count property

I'm working with an ODATA endpoint in SAP and I noticed that SAP sends a __count property when $inlinecount is used, which isn't described in the $metadata unfortunately. Not sure if it can be "turned on" via a query parameter. However it's there.

I looked though the XSLT scripts and couldn't find a "handler" for the __count property. Is it possible to add this to the generated OAS when converting a metadata from SAP OData?

The reason why the __count property is relevant when paging because it contains the total number of results on the server (not a count of returned) which is needed when displaying how many pages there are.

The SAP ODATA response looks like this:

{
  "d": {
    "__count": "42", // shows up when $inlinecount is added
    "results": [...]
  }
}

This is odata-version=2. Not sure how it'll look when going to v4 and using $count

Simplify installation 🚀

It's pretty hard to get this tool up and running. I was wondering if it was possible to simplify the node version in the tools folder.

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

And node-gyp requires python and windows-build-tools it's a bit much.

I found Saxon-JS which claims

Saxon-JS is an XSLT 3.0 run-time written in pure JavaScript.

There might be a license issue, however their license says this

no license is needed for run time deployment on a web browser

Which I guess node sort if is :)

Anyway would you be interested in replacing xslt4node with something a bit easier to install?

WASM is also a possibly.

Generated examples imply that deep insert or update is supported

For entity defined as

<EntityType Name="Other" BaseType="nsp.Base">
    <NavigationProperty Name="Derived" Type="nsp.Derived" Partner="Others" Nullable="false"/>
</EntityType>

Generated sample for POST includes Others

{
  "Name": "string",
  "SomeProperty": "string",
  "Others": [
    {
      "Name": "string"
    }
  ]
}

It should only happen if deep insert/update capabilities are supported

Enumerations for $select,$expand, and $orderby do not include BaseType's properties

Generated $select,$expand, and $orderby enums should include BaseType's properties (recursively)

Generated enpoints for entities with Nullable='false' NavigationProperties contradict the schema

In the attached sample schema EntityType Other can't be created without association to EntityType Derived (kind of 'not null FK' scenario in databases)

One would expect that

POST to /Others will be omitted (as shallow insert allows the creation of Other without association to Derived)
POST to /Deriveds/###/Others would be added (to enforce relationship)

test.api.txt

Can we have the descriptor file generated in a different folder?

Hi,

I'm using this tool to convert my xml to open-api descriptor format and then exposing the same via swagger ui.

This is how im generating:

                    <execution>
                        <id>openapi</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>exec</goal>
                        </goals>
                        <configuration>
                            <workingDirectory>..</workingDirectory>
                            <executable>node</executable>
                            <arguments>
                               <argument>node_modules/odata-openapi/lib/cli.js</argument>
                                <argument>${project.basedir}/src/main/resources/edmx/RequisitionService.xml</argument>                                                  
                            </arguments>											
                        </configuration>
                    </execution>

So my open api file is getting generated in the same folder as the xml. But i want to move my open api file to a different folder and expose only that as a static resource. For this im using the maven resource plugin. But i wanted to know if there is a better way to move the generated file?
I saw a parameter called basePath. can we use this to specify the directory in which we need to generated file?

Is this repository ready for production use?

If so, could we mark one of the latter commits as a 'release'?

Missing schemas

When running the transform shell I get the following errors

error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' example error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' Northwind error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' TripPin error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' odata-rw-v2 error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' Northwind-V2 error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' odata-rw-v3 error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' Northwind-V3 error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json' Northwind-key-as-segment error: Cannot find schema '/home/vminnocci/Documents/code/odata-openapi/tools/openapi-3.0.0.schema.json' error: Cannot find schema '/home/vminnocci/Documents/code/OpenAPI-Specification/schemas/v2.0/schema.json'

odata2openapi2 and transform.sh parity

The files generated from odata2openapi and transform do not appear to be the same. Perhaps I'm not using the exec correctly.

If I want to generated a 3.0 spec file from transform I do the following..
transform.txt
qa-4-metadata.xml http localhost /Core-Informatics/odata/1.0 V4

What would be the odata2openapi equivalent?

odata2openapi --basePath /Core-Informatics/odata/1.0 qa-4-metadata.xml

qa-4-metadata.zip

Invalid conversion of OData metadata to Swagger 2.0

Hi Ralf,

We have an OData metadata v2 content. We are converting it into V4 first. And then converting that V4 content to swagger 2.0.

I have attached the content respectively. The conversion of V4 content to swagger 2.0 generates an invalid JSON file (PFA).

GeneratedSwaggerContent.json.txt
CatalogServiceODataV2.xml.txt

Can you help us know the issue here?

Note:- In the V4-CSDL-to-OpenAPI.xsl, we have changed:
<xsl:param name="openapi-version" select="'3.0.0'" />
to
<xsl:param name="openapi-version" select="'2.0'" />
as we wanted to generate swagger 2.0 content.

Support for Common.FieldControlType/Mandatory

At the Moment there is no support for the following annotation type:
<Annotation Term="Common.FieldControl" EnumMember="Common.FieldControlType/Mandatory"/>

Are there any plans to support and this? For me there seems to be no trivial solution sinnce it is not trivial to expand following XPath expression:

<xsl:apply-templates
      select="edm:Property[@Name=../edm:Key/edm:PropertyRef/@Name and not(edm:Annotation[@Term='Org.OData.Core.V1.Computed' or @Term=concat($coreAlias,'.Computed')])]"
      mode="required" />

Error generating YUML diagram using Javascript version

Not sure if I am doing something wrong

$ odata-openapi3 -d ~/Downloads/metadata.xml
Downloads/metadata.openapi3.json
/dev/odata-openapi-master/lib/csdl2openapi.js:249
const bidirectional = property.$Partner && target && target[property.$Partner].$Partner == propertyName;
^

TypeError: Cannot read property '$Partner' of undefined
at dev/odata-openapi-master/lib/csdl2openapi.js:249:108
at Array.forEach ()
at dev/odata-openapi-master/lib/csdl2openapi.js:244:74
at Array.forEach ()
at dev/odata-openapi-master/lib/csdl2openapi.js:239:18
at Array.forEach ()
at resourceDiagram (/dev/odata-openapi-master/lib/csdl2openapi.js:236:62)
at info (dev/odata-openapi-master/lib/csdl2openapi.js:214:24)
at Object.module.exports.csdl2openapi (dev/odata-openapi-master/lib/csdl2openapi.js:59:15)
at convert (dev/odata-openapi-master/lib/cli.js:72:25)

SAP OData missing __metadata property

I'm working with an ODATA endpoint in SAP and I noticed that SAP sends a __metadata property which isn't described in the $metadata unfortunately. Not sure if it can be "turned on" via a query parameter. However it's there.

I looked though the XSLT scripts and couldn't find a "handler" for the __metadata property. Is it possible to add this to the generated OAS when converting a metadata from SAP OData?

The reason why the __metadata property is relevant is because it contains the etag value for an entity.

The SAP ODATA response looks like this:

{
  "d": {
    "results": [
      {
        "__metadata": {
          "id": "https://.../{dataservice}/{resource}('id')",
          "uri": "https://.../{dataservice}/{resource}('id')",
          "type": "{dataservice}.{resource}",
          "etag": "..."
        },
        "...": "..." // omitted
      }
    ]
  }
}

Function bounded to collection is not handled

I got schema like that
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="MyNamespace"> <Function Name="MyFunction" IsBound="true"> <Parameter Name="bindingParameter" Type="Collection(MyObject)"/> <Parameter Name="from" Type="Edm.DateTimeOffset" Nullable="false"/> <Parameter Name="to" Type="Edm.DateTimeOffset" Nullable="false"/> <ReturnType Type="Collection(MyObject)"/> </Function> ... </Schema>

And that function is not show present in openapi json

OpenApi does not generate (ODataV3)

Hi,

I try to generate openapi (aka swagger) file from attached odata metadata xml. File is generated but it does not include other document.

Cmd

odata2openapi -drp MyMetadata.xml

File result

{
    "openapi": "3.0.0",
    "info": {
        "title": "OData CSDL Document for namespace ",
        "version": "",
        "description": ""
    },
    "paths": {},
    "components": {}
}

Here is my meatadata xml
MyMetadata.txt

Is it anything wrong on odata metadata xml format?

Regards,

Nullable Data Types are not valid against Swagger Specification

The swagger specification says:

OpenAPI 3.0 does not have an explicit null type as in JSON Schema, but you can use nullable: true to specify that the value may be null. Note that null is different from an empty string “”.

Correct

type: integer
nullable: true

Incorrect

type: null

Incorrect as well

type:

integer

null

When you expose a ABAP CDS view using auto exposure then all properties are nullable except the primary key of view. As result the nullable attribute of the property is not "false" and the XSL transformations create something like "type":["string","null"] which is incorrect.

OpenAPI does not support multiple input types

Hi great project!

I used transformed the following metadata url:
http://services.odata.org/V3/OData/OData.svc/$metadata

Received a response that rendered using the Swagger editor:
http://editor.swagger.io/#/

It did generate some response objects as having two possible types like this

"definitions": {
        "ODataDemo.Product": {
            "type": "object",
            "properties": {
                "ID": {
                    "type": "integer",
                    "format": "int32"
                },
                "Name": {
                    "type": ["string", "null"]
                },
                "Description": {
                    "type": ["string", "null"]
                },

Which does not conform to the current OpenAPI spec. It does not look like there is a good way to do it in v2 but if you wanted to conform with the v3 spec null should be as:

"Name": {
                    "type": "string",
                    "nullable": true
                }

Multiple types of responses should be something like:

"Name": {
    "oneOf": [
        {"type": "string"},
        {"type": "integer"}
    ]
}

v3 spec: https://swagger.io/docs/specification/data-models/data-types/
v2 spec: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#header-object

Thanks for working on this!

$batch resource generation from v4 metadata to open API spec

Hi,

Could you please help to understand the $batch resource generation from v4 metadata to open API spec? For v4-transformed-catalog.xml.txt, the "BatchSupported" annotation is not present. Still the $batch resource appear in the generated open API spec.

cheers,
Chinmaya

Generated openApi specification doesn't produce any compileable java client

I created a simple oData Service on SEGW and took the service description from http://...$metadata, looks like that: odata-service-description.xml

This oData Service description produced the following openApi Spec in json: odata-service-description.openapi3.json

Neigther with https://editor.swagger.io/ nor with openApi generator project it's possible to generate a java client from the produced openApi Json.

I use openapi generator as follows:

git log -n 1 origin/master commit dda2f3c1413fe020aa881c3423f24e0c2198859c (HEAD -> master, origin/master, origin/HEAD) Author: xxx Date: Wed Jul 3 12:38:06 2019 +0200

mvn clean package [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Build Order: [INFO] [INFO] openapi-generator-project [pom]...

java -jar modules\openapi-generator-cli\target\openapi-generator-cli.jar generate -i odata-service-description.openapi3.json -g jaxrs-cxf-client -o .\generated-client

An attempt to compile the client produced returns the following error: compile-log.txt

https://editor.swagger.io/ doesn't give any response when trying to generate a client from the given json.

Have i got the workflow correctly? Is there anything wrong with the inital oData Service document or do need to go search for some library issues or do i require a certain version of this project?

I used the follow version of odata-openapi

D:\...\data\project\odata-openapi>git log -n 1 origin/master commit 191fda7544168df3d7f622c680833e74555c6105 (HEAD -> master, origin/master, origin/HEAD) Author: xxxx Date: Wed Jul 3 11:39:47 2019 +0200

Thanks in Advance!
Franz

$metadata payload change odata.context base host url

Hi there,
For api hosted (on premise) behind a load balancer or api gateway, the uri in the payload for document services and entity response (@odata.context,@odata.link), is the uri on the from the hosted server and not the url from the api gateway(etc).

I found a way to change the url on the entity responses metadata,but not for the document services...

Question: There are some alternative for change this url to the hosted base url?

$batch endpoint is still using $ prefix even for 4.01+ schemas

Query parameters do not have $ prefix anymore (as expected). $batch endpoint should also have no prefix.

Converter does not handle circular references

Hello,

I ran into this issue when trying to convert the MSGraph OData metadata to OpenAPI format:

Debugger listening on ws://127.0.0.1:42947/d7be1a7a-c259-4d9f-8a96-d9d08ce2f687
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
/tmp/metadata.openapi3.json
console.js:287
Console.prototype.assert = function assert(expression, ...args) {
                                          ^

RangeError: Maximum call stack size exceeded
    at Console.assert (console.js:287:43)
    at nameParts (/home/*******/odata-openapi/lib/csdl2openapi.js:2066:17)
    at Object.keys.filter.forEach.key (/home/*******/odata-openapi/lib/csdl2openapi.js:760:43)
    at Array.forEach (<anonymous>)
    at primitivePaths (/home/*******/odata-openapi/lib/csdl2openapi.js:759:94)
    at Object.keys.filter.forEach.key (/home/*******/odata-openapi/lib/csdl2openapi.js:765:35)
    at Array.forEach (<anonymous>)
    at primitivePaths (/home/*******/odata-openapi/lib/csdl2openapi.js:759:94)
    at Object.keys.filter.forEach.key (/home/*******/odata-openapi/lib/csdl2openapi.js:765:35)
    at Array.forEach (<anonymous>)
Debugger listening on ws://127.0.0.1:42947/d7be1a7a-c259-4d9f-8a96-d9d08ce2f687
For help, see: https://nodejs.org/en/docs/inspector

The root cause turns out to be that in the MSGraph document there is a circular reference

<EnumType Name="workbookOperationStatus">
    <Member Name="notStarted" Value="0" />
    <Member Name="running" Value="1" />
    <Member Name="succeeded" Value="2" />
    <Member Name="failed" Value="3" />
</EnumType>
...
<EntityType Name="workbookOperation" BaseType="graph.entity">
    <Property Name="status" Type="graph.workbookOperationStatus" Nullable="false" />
    <Property Name="resourceLocation" Type="Edm.String" />
    <Property Name="error" Type="graph.workbookOperationError" />
</EntityType>
<ComplexType Name="workbookSessionInfo">
    <Property Name="id" Type="Edm.String" />
    <Property Name="persistChanges" Type="Edm.Boolean" />
</ComplexType>
<ComplexType Name="Json" />
<ComplexType Name="workbookOperationError">
    <Property Name="code" Type="Edm.String" />
    <Property Name="message" Type="Edm.String" />
    <Property Name="innerError" Type="graph.workbookOperationError" />
</ComplexType>

I have submitted a PR #89 that hopefully fixes the issue. Let me know if this is the correct approach.

Output contains a lot of "anyOf" with just one item

Since it contains only one item it's basically useless but it creates real problem for generating docs.

Example:

odata-openapi/examples/People.openapi3.json

Lines 1166 to 1173 in 48bd0c5

 "Address": { 

 "nullable": true, 

 "anyOf": [ 

 { 

 "$ref": "#/components/schemas/PeopleService.Address" 

 } 

 ] 

 },

operationId

Is it possible to generate operationId as a part of OpenAPI definition? While it is optional from the POV of OpenAPI spec, some clients (https://github.com/swagger-api/swagger-js) rely on its existence.
Thanks!

Error: Cannot find module '/opt/openapi/odata-openapi-master/tools/node_modules/java/build/Release/nodejavabridge_bindings.node'

Hi,

I just did the installation as described. However, when I want to execute
odata-openapi -db metadata.xml
I receive the following error message:
Error: Cannot find module '/opt/openapi/odata-openapi-master/tools/node_modules/java/build/Release/nodejavabridge_bindings.node'
I checked this repository and found out that there is not even a 'build' directory. So
build/Release/nodejavabridge_bindings.node is completely missing.
Did I do something wrong during installation. Have you had such a problem?
I really appreciate any help.
Best regards

Edit:
As this might has something to do with Java, here are some information about my Version:
javac -version javac 1.8.0_231
java -version java version "1.8.0_231" Java(TM) SE Runtime Environment (build 1.8.0_231-b11) Java HotSpot(TM) 64-Bit Server VM (build 25.231-b11, mixed mode)

Edit2:
There have been 2 Warnings during installation:
npm WARN lifecycle [email protected]install: cannot run in wd [email protected] node-gyp rebuild (wd=/opt/openapi/odata-openapi-master/tools/node_modules/java)
npm WARN lifecycle [email protected]postinstall: cannot run in wd [email protected] node postInstall.js (wd=/opt/openapi/odata-openapi-master/tools/node_modules/java)

[email protected]
added 21 packages from 19 contributors and updated 1 package in 2.65s

Incomplete definition generated from OData Metadata

There is one operation called POST /CustomerHeaderSet that we are currently using. In the generated Swagger JSON (2.0), we see that a schema called "CustomerHeader (for create)" gets added, but it only has the association properties and not the properties from the CustomerHeader payload object schema.

Cannot find module 'xslt4node'

Hi,

I got below error message when i run "odata2openapi -drp Northwind.xml cmd after successful install.

i'll appreciate your support

I use NodeJs 8.9.1 and npm 5.5.1 on windows 10.

module.js:538
throw err;

Error: Cannot find module 'xslt4node'
at Function.Module._resolveFilename (module.js:536:15)
at Function.Module._load (module.js:466:25)
at Module.require (module.js:579:17)
at require (internal/module.js:11:18)
at Object. (C:\nodejs\node_modules\npm\node_modules\tools\transform.js:13:17)
at Module._compile (module.js:635:30)
at Object.Module._extensions..js (module.js:646:10)
at Module.load (module.js:554:32)
at tryModuleLoad (module.js:497:12)
at Function.Module._load (module.js:489:3)

Regards,

on MacOS...Error processing OData v3.0 $metadata XML file...

my odata3-metadata.xml file is from a clients Private (non-public) OData v3.0 web service.

The head of my input file from $metadata file is shown below

hholtmann on hhMacBookPro2014 in ~/proj/iw/openAPI/client
➜ head odata3-metadata.xml

<edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx">
<edmx:DataServices m:DataServiceVersion="3.0" m:MaxDataServiceVersion="3.0" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">

hholtmann on hhMacBookPro2014 in ~/proj/iw/openAPI/cmms

No problems installing Node.js and other packages required for macOS

But i get errors when i try to invoke the tool as per instructions

SyntaxError: Unexpected token , in JSON at position 156367
at JSON.parse ()
at xslt4node.transform (/Users/hholtmann/proj/iw/odata-openapi/tools/transform.js:142:66)

What else can I provide to help get past this.

The instructions are NOT clear how to force an OData v3.0 $metadata XML file to Open Data JSON file that works?

What am I doing wrong?

It gives error for the contained entity as its key is hidden

I am generating OpenAPI specification from the edmx using the transform script by "odata-openapi -dpo 2.0 WorkforceAPI.xml", but it gives error for the contained entity as its key is hidden.

I have attached files as attached. As .xml file is not supported to upload, I have changed it to WorkforceAPI.txt to upload.WorkforceAPI.xml

WorkforceAPI.txt

	"Address": {
	"nullable": true,
	"anyOf": [
	{
	"$ref": "#/components/schemas/PeopleService.Address"
	}
	]
	},

oasis-tcs / odata-openapi Goto Github PK

odata-openapi's Introduction

README

Description

Contributions

Licensing

Further Description of this Repository

Contact

odata-openapi's People

Contributors

Stargazers

Watchers

Forkers

odata-openapi's Issues

Correct

Incorrect

Incorrect as well

Recommend Projects

Recommend Topics

Recommend Org

Jobs