From c401ae6d3ed313733d3318c7ff222d65ce527085 Mon Sep 17 00:00:00 2001 From: Uri Sarid Date: Wed, 19 Jul 2017 17:11:46 -0700 Subject: [PATCH 1/4] Update guidelines for v3 and Swagger --> OAS --- guidelines/README.md | 4 ---- guidelines/{ => v2.0}/EXTENSIONS.md | 28 ++++++++++++++-------------- guidelines/v2.0/README.md | 4 ++++ guidelines/{ => v2.0}/REUSE.md | 0 4 files changed, 18 insertions(+), 18 deletions(-) delete mode 100644 guidelines/README.md rename guidelines/{ => v2.0}/EXTENSIONS.md (61%) create mode 100644 guidelines/v2.0/README.md rename guidelines/{ => v2.0}/REUSE.md (100%) 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/EXTENSIONS.md b/guidelines/v2.0/EXTENSIONS.md similarity index 61% rename from guidelines/EXTENSIONS.md rename to guidelines/v2.0/EXTENSIONS.md index be10b14984..52e2a1f69f 100644 --- a/guidelines/EXTENSIONS.md +++ b/guidelines/v2.0/EXTENSIONS.md @@ -1,21 +1,21 @@ -# Swagger Extensions +# OpenAPI Extensions -The Swagger 2.0 specification allows for custom properties to be added at several places within a Swagger definition, allowing +The OpenAPI Specification version 2.0 allows for custom properties to be added at several places within an OpenAPI 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) +* within the [info object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#info-object) +* within the [paths object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#paths-object) +* within the [path-item object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#path-item-object) +* within the [operation object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#operationObject) +* within the [parameter object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#parameterObject) +* within the [responses object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#responses-object) +* within the [tag object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#tag-object) +* within the [security-scheme object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/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: +For example, a vendor extension that adds apis.json specific metadata to an OpenAPI definition might look as follows: ```json { @@ -59,8 +59,8 @@ For example, a vendor extension that adds apis.json specific metadata a Swagger } ``` -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. +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: @@ -89,4 +89,4 @@ An API consumer reading these parameter definitions could interpret this as havi ## Annotations -The Swagger-specific annotations currently available for jax-rs APIs do not support the addition of extension data. +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 From 6d40370256a0bab01201c9474a9d584060c8dcd4 Mon Sep 17 00:00:00 2001 From: Uri Sarid Date: Tue, 25 Jul 2017 11:41:36 -0700 Subject: [PATCH 2/4] Update the references in EXTENSIONS.md to refer to whatever is the current version --- guidelines/v2.0/EXTENSIONS.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guidelines/v2.0/EXTENSIONS.md b/guidelines/v2.0/EXTENSIONS.md index 52e2a1f69f..952a3f182a 100644 --- a/guidelines/v2.0/EXTENSIONS.md +++ b/guidelines/v2.0/EXTENSIONS.md @@ -6,14 +6,14 @@ 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/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#info-object) -* within the [paths object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#paths-object) -* within the [path-item object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#path-item-object) -* within the [operation object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#operationObject) -* within the [parameter object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#parameterObject) -* within the [responses object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#responses-object) -* within the [tag object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#tag-object) -* within the [security-scheme object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#security-scheme-object) +* 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: From 84f999189cacbffa178e412a377757f88a4fdf82 Mon Sep 17 00:00:00 2001 From: Uri Sarid Date: Tue, 25 Jul 2017 11:44:28 -0700 Subject: [PATCH 3/4] definition -> document --- guidelines/v2.0/EXTENSIONS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guidelines/v2.0/EXTENSIONS.md b/guidelines/v2.0/EXTENSIONS.md index 952a3f182a..e0c1124034 100644 --- a/guidelines/v2.0/EXTENSIONS.md +++ b/guidelines/v2.0/EXTENSIONS.md @@ -1,6 +1,6 @@ # OpenAPI Extensions -The OpenAPI Specification version 2.0 allows for custom properties to be added at several places within an OpenAPI definition, allowing +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. From 2070f3c3afae7006c9daa0a386fdcae4b05391d1 Mon Sep 17 00:00:00 2001 From: Uri Sarid Date: Tue, 25 Jul 2017 11:47:57 -0700 Subject: [PATCH 4/4] Add EXTENSIONS.md file at the root of the guidelines folder to avoid link breakage --- guidelines/EXTENSIONS.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guidelines/EXTENSIONS.md diff --git a/guidelines/EXTENSIONS.md b/guidelines/EXTENSIONS.md new file mode 100644 index 0000000000..2bddf6fd9b --- /dev/null +++ b/guidelines/EXTENSIONS.md @@ -0,0 +1 @@ +For OpenAPI Specification version 2.0, please see [v2.0/EXTENSIONS.md](v2.0/EXTENSIONS.md)