Skip to content

Commit 1bb321a

Browse files
author
Ron
authored
Merge pull request OAI#1280 from usarid/Update-guidelines-for-v3
Update guidelines for v3 and Swagger --> OAS
2 parents c43dd44 + 2070f3c commit 1bb321a

File tree

5 files changed

+97
-96
lines changed

5 files changed

+97
-96
lines changed

‎guidelines/EXTENSIONS.md

Lines changed: 1 addition & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1 @@
1-
# Swagger Extensions
2-
3-
The Swagger 2.0 specification allows for custom properties to be added at several places within a Swagger definition, allowing
4-
API providers to extend the meta-data provided for their REST APIs as needed. Extension properties are always
5-
prefixed by "x-" and can have any valid JSON format value.
6-
7-
Currently extension properties are supported in the following definition objects:
8-
9-
* within the [info object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#info-object)
10-
* within the [paths object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#paths-object)
11-
* within the [path-item object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#path-item-object)
12-
* within the [operation object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
13-
* within the [parameter object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject)
14-
* within the [responses object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responses-object)
15-
* within the [tag object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#tag-object)
16-
* within the [security-scheme object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#security-scheme-object)
17-
18-
For example, a vendor extension that adds apis.json specific metadata a Swagger definition might look as follows:
19-
20-
```json
21-
{
22-
"swagger": "2.0",
23-
"info": {
24-
"version": "1.0",
25-
"title": "Analysis",
26-
"description" : "Provides access to blog posts and analysis across the API Evangelist network.",
27-
"x-apis-json" : {
28-
"image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png",
29-
"humanURL": "http://developer.apievangelist.com",
30-
"baseURL": "http://api.apievangelist.com/definitions/Analysis",
31-
"tags": [
32-
"blog",
33-
"industry",
34-
"analysis",
35-
"new",
36-
"API",
37-
"Application Programming Interface"
38-
],
39-
"properties": [
40-
{
41-
"type": "X-signup",
42-
"url": "https://apievangelist.3scale.net/"
43-
},
44-
{
45-
"type": "X-blog",
46-
"url": "http://developer.apievangelist.com/blog/"
47-
},
48-
{
49-
"type": "X-apicommonsmanifest",
50-
"url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json"
51-
}
52-
],
53-
}
54-
},
55-
"basePath": "/",
56-
"paths": {
57-
...
58-
}
59-
}
60-
```
61-
62-
This could be used by corresponding tooling that builds apis.json files for swagger definitions, the advantage being that all metadata
63-
for a Swagger API is within one definition instead of spread out amongst multiple files.
64-
65-
Another (simplified) example could be how to specify a [JWE encryption](http://hdknr.github.io/docs/identity/jwe.html) policy to parameters,
66-
for example as follows:
67-
68-
```json
69-
{
70-
...
71-
"socialSecurityNumber": {
72-
"name": "socialSecurityNumber",
73-
"in": "query",
74-
"description": "a social security number",
75-
"required": false,
76-
"type": "string",
77-
"x-jwe-encryption" : {
78-
"algorithm" : "RSA-OAEP",
79-
"encryption" : "A256GCM"
80-
}
81-
}
82-
}
83-
...
84-
}
85-
86-
```
87-
An API consumer reading these parameter definitions could interpret this as having to encrypt the skip parameter in line
88-
with the JWE standard.
89-
90-
## Annotations
91-
92-
The Swagger-specific annotations currently available for jax-rs APIs do not support the addition of extension data.
1+
For OpenAPI Specification version 2.0, please see [v2.0/EXTENSIONS.md](v2.0/EXTENSIONS.md)

‎guidelines/README.md

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎guidelines/v2.0/EXTENSIONS.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# OpenAPI Extensions
2+
3+
The OpenAPI Specification version 2.0 allows for custom properties to be added at several places within an OpenAPI document., allowing
4+
API providers to extend the meta-data provided for their REST APIs as needed. Extension properties are always
5+
prefixed by "x-" and can have any valid JSON format value.
6+
7+
Currently extension properties are supported in the following definition objects:
8+
9+
* within the [info object](/versions/2.0.md#info-object)
10+
* within the [paths object](/versions/2.0.md#paths-object)
11+
* within the [path-item object](/versions/2.0.md#path-item-object)
12+
* within the [operation object](/versions/2.0.md#operationObject)
13+
* within the [parameter object](/versions/2.0.md#parameterObject)
14+
* within the [responses object](/versions/2.0.md#responses-object)
15+
* within the [tag object](/versions/2.0.md#tag-object)
16+
* within the [security-scheme object](/versions/2.0.md#security-scheme-object)
17+
18+
For example, a vendor extension that adds apis.json specific metadata to an OpenAPI definition might look as follows:
19+
20+
```json
21+
{
22+
"swagger": "2.0",
23+
"info": {
24+
"version": "1.0",
25+
"title": "Analysis",
26+
"description" : "Provides access to blog posts and analysis across the API Evangelist network.",
27+
"x-apis-json" : {
28+
"image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png",
29+
"humanURL": "http://developer.apievangelist.com",
30+
"baseURL": "http://api.apievangelist.com/definitions/Analysis",
31+
"tags": [
32+
"blog",
33+
"industry",
34+
"analysis",
35+
"new",
36+
"API",
37+
"Application Programming Interface"
38+
],
39+
"properties": [
40+
{
41+
"type": "X-signup",
42+
"url": "https://apievangelist.3scale.net/"
43+
},
44+
{
45+
"type": "X-blog",
46+
"url": "http://developer.apievangelist.com/blog/"
47+
},
48+
{
49+
"type": "X-apicommonsmanifest",
50+
"url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json"
51+
}
52+
],
53+
}
54+
},
55+
"basePath": "/",
56+
"paths": {
57+
...
58+
}
59+
}
60+
```
61+
62+
This could be used by corresponding tooling that builds apis.json files for OpenAPI definitions, the advantage being that all metadata
63+
for the API is within one definition instead of spread out amongst multiple files.
64+
65+
Another (simplified) example could be how to specify a [JWE encryption](http://hdknr.github.io/docs/identity/jwe.html) policy to parameters,
66+
for example as follows:
67+
68+
```json
69+
{
70+
...
71+
"socialSecurityNumber": {
72+
"name": "socialSecurityNumber",
73+
"in": "query",
74+
"description": "a social security number",
75+
"required": false,
76+
"type": "string",
77+
"x-jwe-encryption" : {
78+
"algorithm" : "RSA-OAEP",
79+
"encryption" : "A256GCM"
80+
}
81+
}
82+
}
83+
...
84+
}
85+
86+
```
87+
An API consumer reading these parameter definitions could interpret this as having to encrypt the skip parameter in line
88+
with the JWE standard.
89+
90+
## Annotations
91+
92+
The OpenAPI-specific annotations currently available for jax-rs APIs do not support the addition of extension data.

‎guidelines/v2.0/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
## Guidelines for OpenAPI Definitions
2+
3+
* [Reuse](REUSE.md) of OpenAPI definitions
4+
* [Extending](EXTENSIONS.md) OpenAPI definitions with custom metadata

‎guidelines/REUSE.md renamed to ‎guidelines/v2.0/REUSE.md

File renamed without changes.

0 commit comments

Comments
 (0)