Skip to content

Commit 51871a9

Browse files
HeikoTheissenHeikoTheissen
authored
Merge branch 'main' into resolve-paths
2 parents 6419560 + ef9e23e commit 51871a9

27 files changed

+1349
-622
lines changed

‎.vscode/extensions.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"hbenl.vscode-mocha-test-adapter",
77
"hbenl.vscode-test-explorer",
88
"redhat.vscode-xml",
9-
"streetsidesoftware.code-spell-checker"
9+
"streetsidesoftware.code-spell-checker",
10+
"yzhang.markdown-all-in-one"
1011
]
1112
}

‎README.md‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,31 +24,32 @@
2424

2525
<div>
2626
<h3>Contributions</h3>
27-
<p>As stated in this repository's <a href="https://github.com/oasis-tcs/odata-openapi/blob/master/CONTRIBUTING.md">CONTRIBUTING file</a>, 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 <a href="https://www.oasis-open.org/join/participation-instructions">participate</a> 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 <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
27+
<p>As stated in this repository's <a href="https://github.com/oasis-tcs/odata-openapi/blob/main/CONTRIBUTING.md">CONTRIBUTING file</a>, 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 <a href="https://www.oasis-open.org/join/participation-instructions">participate</a> 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 <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
2828
</div>
2929

3030
<div>
3131
<h3>Licensing</h3>
32-
<p>Please see the <a href="https://github.com/oasis-tcs/odata-openapi/blob/master/LICENSE.md">LICENSE</a> 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 <a href="https://github.com/oasis-tcs/odata-openapi/blob/master/LICENSE.md">LICENSE</a> file.</p>
32+
<p>Please see the <a href="https://github.com/oasis-tcs/odata-openapi/blob/main/LICENSE.md">LICENSE</a> 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 <a href="https://github.com/oasis-tcs/odata-openapi/blob/main/LICENSE.md">LICENSE</a> file.</p>
3333
</div>
3434

35-
3635
<h3>Further Description of this Repository</h3>
3736

38-
The OData TC has published the [OData to OpenAPI Mapping Version 1.0](http://docs.oasis-open.org/odata/odata-openapi/v1.0/odata-openapi-v1.0.html), 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](lib), and [one using XSLT](tools).
37+
The OData TC has published the [OData to OpenAPI Mapping Version 1.0](http://docs.oasis-open.org/odata/odata-openapi/v1.0/odata-openapi-v1.0.html), 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](https://github.com/oasis-tcs/odata-openapi/blob/main/lib), and [one using XSLT](https://github.com/oasis-tcs/odata-openapi/blob/main/tools).
3938

40-
The [`examples` folder](examples) contains [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification) descriptions that have been created from the XML `$metadata` documents of live and example OData services with these proof-of-concept implementations.
39+
The [`examples` folder](https://github.com/oasis-tcs/odata-openapi/blob/main/examples) contains [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification) descriptions that have been created from the XML `$metadata` documents of live and example OData services with these proof-of-concept implementations.
4140

4241
The entity-relationship diagrams visualizing the resource models of each service are generated on-the-fly with [yUML](http://yuml.me/).
4342

4443
OpenAPI descriptions for live example OData services at [www.odata.org](http://www.odata.org/)
45-
- [TripPin (read/write)](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/master/examples/TripPin.openapi3.json)
46-
- [Simple read/write service](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/master/examples/example.openapi3.json)
47-
- [Northwind (read)](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/master/examples/Northwind.openapi3.json)
44+
45+
- [TripPin (read/write)](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/main/examples/TripPin.openapi3.json)
46+
- [Simple read/write service](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/main/examples/example.openapi3.json)
47+
- [Northwind (read)](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/main/examples/Northwind.openapi3.json)
4848

4949
OpenAPI descriptions for OData services that reference each other (cross-service references)
50-
- [People](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/master/examples/People.openapi3.json)
51-
- [Products](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/master/examples/Products.openapi3.json)
50+
51+
- [People](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/main/examples/People.openapi3.json)
52+
- [Products](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/main/examples/Products.openapi3.json)
5253

5354
<div>
5455
<h3>Contact</h3>

‎doc/FAQ.md‎

Lines changed: 137 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,137 @@
1-
# Frequently Asked Questions
2-
3-
Examples for typical questions on how to fine-tune the generated OpenAPI descriptions.
4-
5-
The examples here do not cover the full list of [supported annotions](Annotations.md).
6-
7-
<!-- TOC depthfrom:2 -->
8-
9-
- [How to suppress GET list and by-key on an entity set?](#how-to-suppress-get-list-and-by-key-on-an-entity-set)
10-
- [How to suppress GET list on an entity set?](#how-to-suppress-get-list-on-an-entity-set)
11-
- [How to suppress GET by-key on an entity set?](#how-to-suppress-get-by-key-on-an-entity-set)
12-
- [How to suppress GET and POST along all navigation properties?](#how-to-suppress-get-and-post-along-all-navigation-properties)
13-
- [How to suppress GET and POST along a specific navigation property?](#how-to-suppress-get-and-post-along-a-specific-navigation-property)
14-
- [How to suppress GET along a specific navigation property?](#how-to-suppress-get-along-a-specific-navigation-property)
15-
- [How to suppress POST along a specific navigation property?](#how-to-suppress-post-along-a-specific-navigation-property)
16-
- [Can I have multiple NavigationRestrictions annotations for the same entity set?](#can-i-have-multiple-navigationrestrictions-annotations-for-the-same-entity-set)
17-
- [Can I have multiple records for the same navigation property in the RestrictedProperties collection?](#can-i-have-multiple-records-for-the-same-navigation-property-in-the-restrictedproperties-collection)
18-
19-
<!-- /TOC -->
20-
21-
## How to suppress GET (list and by-key) on an entity set?
22-
23-
To suppress both types of GET requests to an entity set, annotate it with
24-
25-
```xml
26-
<Annotation Term="Capabilities.ReadRestrictions">
27-
<Record>
28-
<PropertyValue Property="Readable" Bool="false" />
29-
</Record>
30-
</Annotation>
31-
```
32-
33-
## How to suppress GET (list) on an entity set?
34-
35-
To suppress only GET list requests to an entity set and still allow GET by-key, annotate it with
36-
37-
```xml
38-
<Annotation Term="Capabilities.ReadRestrictions">
39-
<Record>
40-
<PropertyValue Property="Readable" Bool="false" />
41-
<PropertyValue Property="ReadByKeyRestrictions">
42-
<Record>
43-
<PropertyValue Property="Readable" Bool="true" />
44-
</Record>
45-
</PropertyValue>
46-
</Record>
47-
</Annotation>
48-
```
49-
50-
## How to suppress GET (by-key) on an entity set?
51-
52-
To suppress only GET by-key requests to an entity set and still allow GET list, annotate it with
53-
54-
```xml
55-
<Annotation Term="Capabilities.ReadRestrictions">
56-
<Record>
57-
<PropertyValue Property="ReadByKeyRestrictions">
58-
<Record>
59-
<PropertyValue Property="Readable" Bool="false" />
60-
</Record>
61-
</PropertyValue>
62-
</Record>
63-
</Annotation>
64-
```
65-
66-
## How to suppress GET and POST along all navigation properties?
67-
68-
```xml
69-
<Annotation Term="Capabilities.NavigationRestrictions">
70-
<Record>
71-
<PropertyValue Property="Navigability" EnumMember="Capabilities.NavigationType/None" />
72-
</Record>
73-
</Annotation>
74-
```
75-
76-
## How to suppress GET and POST along a specific navigation property?
77-
78-
```xml
79-
<Annotation Term="Capabilities.NavigationRestrictions">
80-
<Record>
81-
<PropertyValue Property="RestrictedProperties">
82-
<Collection>
83-
<Record>
84-
<PropertyValue Property="NavigationProperty" NavigationPropertyPath="Foo" />
85-
<PropertyValue Property="Navigability" EnumMember="Capabilities.NavigationType/None" />
86-
</Record>
87-
</Collection>
88-
</PropertyValue>
89-
</Record>
90-
</Annotation>
91-
```
92-
93-
## How to suppress GET along a specific navigation property?
94-
95-
```xml
96-
<Annotation Term="Capabilities.NavigationRestrictions">
97-
<Record>
98-
<PropertyValue Property="RestrictedProperties">
99-
<Collection>
100-
<Record>
101-
<PropertyValue Property="NavigationProperty" NavigationPropertyPath="Foo" />
102-
<PropertyValue Property="ReadRestrictions">
103-
<Record>
104-
<PropertyValue Property="Readable" Bool="false" />
105-
</Record>
106-
</PropertyValue>
107-
</Record>
108-
</Collection>
109-
</PropertyValue>
110-
</Record>
111-
</Annotation>
112-
```
113-
114-
## How to suppress POST along a specific navigation property?
115-
116-
```xml
117-
<Annotation Term="Capabilities.NavigationRestrictions">
118-
<Record>
119-
<PropertyValue Property="RestrictedProperties">
120-
<Collection>
121-
<Record>
122-
<PropertyValue Property="NavigationProperty" NavigationPropertyPath="Foo" />
123-
<PropertyValue Property="InsertRestrictions">
124-
<Record>
125-
<PropertyValue Property="Insertable" Bool="false" />
126-
</Record>
127-
</PropertyValue>
128-
</Record>
129-
</Collection>
130-
</PropertyValue>
131-
</Record>
132-
</Annotation>
133-
```
134-
135-
## Can I have multiple `NavigationRestrictions` annotations for the same entity set?
136-
137-
No, you have to combine all restrictions for an entity set into a single annotation with term `Capabilities.NavigationRestrictions`.
138-
139-
## Can I have multiple records for the same navigation property in the `RestrictedProperties` collection?
140-
141-
No, you have to combine all restrictions for a navigation proeprty into a single record.
1+
# Frequently Asked Questions <!-- omit in toc -->
2+
3+
Examples for typical questions on how to fine-tune the generated OpenAPI descriptions.
4+
5+
The examples here do not cover the full list of [supported annotions](Annotations.md).
6+
7+
- [How to suppress GET (list and by-key) on an entity set?](#how-to-suppress-get-list-and-by-key-on-an-entity-set)
8+
- [How to suppress GET (list) on an entity set?](#how-to-suppress-get-list-on-an-entity-set)
9+
- [How to suppress GET (by-key) on an entity set?](#how-to-suppress-get-by-key-on-an-entity-set)
10+
- [How to suppress GET and POST along all navigation properties?](#how-to-suppress-get-and-post-along-all-navigation-properties)
11+
- [How to suppress GET and POST along a specific navigation property?](#how-to-suppress-get-and-post-along-a-specific-navigation-property)
12+
- [How to suppress GET along a specific navigation property?](#how-to-suppress-get-along-a-specific-navigation-property)
13+
- [How to suppress POST along a specific navigation property?](#how-to-suppress-post-along-a-specific-navigation-property)
14+
- [Can I have multiple `NavigationRestrictions` annotations for the same entity set?](#can-i-have-multiple-navigationrestrictions-annotations-for-the-same-entity-set)
15+
- [Can I have multiple records for the same navigation property in the `RestrictedProperties` collection?](#can-i-have-multiple-records-for-the-same-navigation-property-in-the-restrictedproperties-collection)
16+
17+
## How to suppress GET (list and by-key) on an entity set?
18+
19+
To suppress both types of GET requests to an entity set, annotate it with
20+
21+
```xml
22+
<Annotation Term="Capabilities.ReadRestrictions">
23+
<Record>
24+
<PropertyValue Property="Readable" Bool="false" />
25+
</Record>
26+
</Annotation>
27+
```
28+
29+
## How to suppress GET (list) on an entity set?
30+
31+
To suppress only GET list requests to an entity set and still allow GET by-key, annotate it with
32+
33+
```xml
34+
<Annotation Term="Capabilities.ReadRestrictions">
35+
<Record>
36+
<PropertyValue Property="Readable" Bool="false" />
37+
<PropertyValue Property="ReadByKeyRestrictions">
38+
<Record>
39+
<PropertyValue Property="Readable" Bool="true" />
40+
</Record>
41+
</PropertyValue>
42+
</Record>
43+
</Annotation>
44+
```
45+
46+
## How to suppress GET (by-key) on an entity set?
47+
48+
To suppress only GET by-key requests to an entity set and still allow GET list, annotate it with
49+
50+
```xml
51+
<Annotation Term="Capabilities.ReadRestrictions">
52+
<Record>
53+
<PropertyValue Property="ReadByKeyRestrictions">
54+
<Record>
55+
<PropertyValue Property="Readable" Bool="false" />
56+
</Record>
57+
</PropertyValue>
58+
</Record>
59+
</Annotation>
60+
```
61+
62+
## How to suppress GET and POST along all navigation properties?
63+
64+
```xml
65+
<Annotation Term="Capabilities.NavigationRestrictions">
66+
<Record>
67+
<PropertyValue Property="Navigability" EnumMember="Capabilities.NavigationType/None" />
68+
</Record>
69+
</Annotation>
70+
```
71+
72+
## How to suppress GET and POST along a specific navigation property?
73+
74+
```xml
75+
<Annotation Term="Capabilities.NavigationRestrictions">
76+
<Record>
77+
<PropertyValue Property="RestrictedProperties">
78+
<Collection>
79+
<Record>
80+
<PropertyValue Property="NavigationProperty" NavigationPropertyPath="Foo" />
81+
<PropertyValue Property="Navigability" EnumMember="Capabilities.NavigationType/None" />
82+
</Record>
83+
</Collection>
84+
</PropertyValue>
85+
</Record>
86+
</Annotation>
87+
```
88+
89+
## How to suppress GET along a specific navigation property?
90+
91+
```xml
92+
<Annotation Term="Capabilities.NavigationRestrictions">
93+
<Record>
94+
<PropertyValue Property="RestrictedProperties">
95+
<Collection>
96+
<Record>
97+
<PropertyValue Property="NavigationProperty" NavigationPropertyPath="Foo" />
98+
<PropertyValue Property="ReadRestrictions">
99+
<Record>
100+
<PropertyValue Property="Readable" Bool="false" />
101+
</Record>
102+
</PropertyValue>
103+
</Record>
104+
</Collection>
105+
</PropertyValue>
106+
</Record>
107+
</Annotation>
108+
```
109+
110+
## How to suppress POST along a specific navigation property?
111+
112+
```xml
113+
<Annotation Term="Capabilities.NavigationRestrictions">
114+
<Record>
115+
<PropertyValue Property="RestrictedProperties">
116+
<Collection>
117+
<Record>
118+
<PropertyValue Property="NavigationProperty" NavigationPropertyPath="Foo" />
119+
<PropertyValue Property="InsertRestrictions">
120+
<Record>
121+
<PropertyValue Property="Insertable" Bool="false" />
122+
</Record>
123+
</PropertyValue>
124+
</Record>
125+
</Collection>
126+
</PropertyValue>
127+
</Record>
128+
</Annotation>
129+
```
130+
131+
## Can I have multiple `NavigationRestrictions` annotations for the same entity set?
132+
133+
No, you have to combine all restrictions for an entity set into a single annotation with term `Capabilities.NavigationRestrictions`.
134+
135+
## Can I have multiple records for the same navigation property in the `RestrictedProperties` collection?
136+
137+
No, you have to combine all restrictions for a navigation proeprty into a single record.

‎lib/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,4 +50,4 @@ Options:
5050

5151
## Supported Annotations
5252

53-
The mapping can be fine-tuned via [annotations](../doc/Annotations.md) in the CSDL (`$metadata`) XML documents.
53+
The mapping can be fine-tuned via [annotations](https://github.com/oasis-tcs/odata-openapi/blob/main/doc/Annotations.md) in the CSDL (`$metadata`) XML documents.

0 commit comments

Comments
 (0)