diff --git a/guidelines/EXTENSIONS.md b/guidelines/EXTENSIONS.md index be10b14984..2bddf6fd9b 100644 --- a/guidelines/EXTENSIONS.md +++ b/guidelines/EXTENSIONS.md @@ -1,92 +1 @@ -# Swagger Extensions - -The Swagger 2.0 specification allows for custom properties to be added at several places within a Swagger definition, allowing -API providers to extend the meta-data provided for their REST APIs as needed. Extension properties are always -prefixed by "x-" and can have any valid JSON format value. - -Currently extension properties are supported in the following definition objects: - -* within the [info object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#info-object) -* within the [paths object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#paths-object) -* within the [path-item object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#path-item-object) -* within the [operation object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject) -* within the [parameter object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject) -* within the [responses object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responses-object) -* within the [tag object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#tag-object) -* within the [security-scheme object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#security-scheme-object) - -For example, a vendor extension that adds apis.json specific metadata a Swagger definition might look as follows: - -```json -{ - "swagger": "2.0", - "info": { - "version": "1.0", - "title": "Analysis", - "description" : "Provides access to blog posts and analysis across the API Evangelist network.", - "x-apis-json" : { - "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png", - "humanURL": "http://developer.apievangelist.com", - "baseURL": "http://api.apievangelist.com/definitions/Analysis", - "tags": [ - "blog", - "industry", - "analysis", - "new", - "API", - "Application Programming Interface" - ], - "properties": [ - { - "type": "X-signup", - "url": "https://apievangelist.3scale.net/" - }, - { - "type": "X-blog", - "url": "http://developer.apievangelist.com/blog/" - }, - { - "type": "X-apicommonsmanifest", - "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json" - } - ], - } - }, - "basePath": "/", - "paths": { - ... - } -} -``` - -This could be used by corresponding tooling that builds apis.json files for swagger definitions, the advantage being that all metadata -for a Swagger API is within one definition instead of spread out amongst multiple files. - -Another (simplified) example could be how to specify a [JWE encryption](http://hdknr.github.io/docs/identity/jwe.html) policy to parameters, - for example as follows: - -```json -{ - ... - "socialSecurityNumber": { - "name": "socialSecurityNumber", - "in": "query", - "description": "a social security number", - "required": false, - "type": "string", - "x-jwe-encryption" : { - "algorithm" : "RSA-OAEP", - "encryption" : "A256GCM" - } - } - } - ... -} - -``` -An API consumer reading these parameter definitions could interpret this as having to encrypt the skip parameter in line - with the JWE standard. - -## Annotations - -The Swagger-specific annotations currently available for jax-rs APIs do not support the addition of extension data. +For OpenAPI Specification version 2.0, please see [v2.0/EXTENSIONS.md](v2.0/EXTENSIONS.md) diff --git a/guidelines/README.md b/guidelines/README.md deleted file mode 100644 index b18a2a2b1d..0000000000 --- a/guidelines/README.md +++ /dev/null @@ -1,4 +0,0 @@ -## Guidelines for Swagger definitions - -* [Reuse](REUSE.md) of Swagger definitions -* [Extending](EXTENSIONS.md) Swagger definitions with custom metadata diff --git a/guidelines/v2.0/EXTENSIONS.md b/guidelines/v2.0/EXTENSIONS.md new file mode 100644 index 0000000000..e0c1124034 --- /dev/null +++ b/guidelines/v2.0/EXTENSIONS.md @@ -0,0 +1,92 @@ +# OpenAPI Extensions + +The OpenAPI Specification version 2.0 allows for custom properties to be added at several places within an OpenAPI document., allowing +API providers to extend the meta-data provided for their REST APIs as needed. Extension properties are always +prefixed by "x-" and can have any valid JSON format value. + +Currently extension properties are supported in the following definition objects: + +* within the [info object](/versions/2.0.md#info-object) +* within the [paths object](/versions/2.0.md#paths-object) +* within the [path-item object](/versions/2.0.md#path-item-object) +* within the [operation object](/versions/2.0.md#operationObject) +* within the [parameter object](/versions/2.0.md#parameterObject) +* within the [responses object](/versions/2.0.md#responses-object) +* within the [tag object](/versions/2.0.md#tag-object) +* within the [security-scheme object](/versions/2.0.md#security-scheme-object) + +For example, a vendor extension that adds apis.json specific metadata to an OpenAPI definition might look as follows: + +```json +{ + "swagger": "2.0", + "info": { + "version": "1.0", + "title": "Analysis", + "description" : "Provides access to blog posts and analysis across the API Evangelist network.", + "x-apis-json" : { + "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png", + "humanURL": "http://developer.apievangelist.com", + "baseURL": "http://api.apievangelist.com/definitions/Analysis", + "tags": [ + "blog", + "industry", + "analysis", + "new", + "API", + "Application Programming Interface" + ], + "properties": [ + { + "type": "X-signup", + "url": "https://apievangelist.3scale.net/" + }, + { + "type": "X-blog", + "url": "http://developer.apievangelist.com/blog/" + }, + { + "type": "X-apicommonsmanifest", + "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json" + } + ], + } + }, + "basePath": "/", + "paths": { + ... + } +} +``` + +This could be used by corresponding tooling that builds apis.json files for OpenAPI definitions, the advantage being that all metadata +for the API is within one definition instead of spread out amongst multiple files. + +Another (simplified) example could be how to specify a [JWE encryption](http://hdknr.github.io/docs/identity/jwe.html) policy to parameters, + for example as follows: + +```json +{ + ... + "socialSecurityNumber": { + "name": "socialSecurityNumber", + "in": "query", + "description": "a social security number", + "required": false, + "type": "string", + "x-jwe-encryption" : { + "algorithm" : "RSA-OAEP", + "encryption" : "A256GCM" + } + } + } + ... +} + +``` +An API consumer reading these parameter definitions could interpret this as having to encrypt the skip parameter in line + with the JWE standard. + +## Annotations + +The OpenAPI-specific annotations currently available for jax-rs APIs do not support the addition of extension data. diff --git a/guidelines/v2.0/README.md b/guidelines/v2.0/README.md new file mode 100644 index 0000000000..4b1bea7f98 --- /dev/null +++ b/guidelines/v2.0/README.md @@ -0,0 +1,4 @@ +## Guidelines for OpenAPI Definitions + +* [Reuse](REUSE.md) of OpenAPI definitions +* [Extending](EXTENSIONS.md) OpenAPI definitions with custom metadata diff --git a/guidelines/REUSE.md b/guidelines/v2.0/REUSE.md similarity index 100% rename from guidelines/REUSE.md rename to guidelines/v2.0/REUSE.md