From 970566d5ca236a5ce1a02fb7d617fdbd07df88db Mon Sep 17 00:00:00 2001 From: Helen Kosova Date: Wed, 26 Jul 2017 11:29:30 +0300 Subject: [PATCH 01/12] Add quotes around response statuses in standalone 3.0 examples --- examples/v3.0/api-with-examples.yaml | 8 ++++---- examples/v3.0/petstore-expanded.yaml | 8 ++++---- examples/v3.0/petstore.yaml | 6 +++--- examples/v3.0/uber.yaml | 10 +++++----- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 8fdee415ad..ae491420e5 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -8,7 +8,7 @@ paths: operationId: listVersionsv2 summary: List API versions responses: - 200: + "200": description: |- 200 response content: @@ -41,7 +41,7 @@ paths: } ] } - 300: + "300": description: |- 300 response content: @@ -80,7 +80,7 @@ paths: operationId: getVersionDetailsv2 summary: Show API version details responses: - 200: + "200": description: |- 200 response content: @@ -125,7 +125,7 @@ paths: ] } } - 203: + "203": description: |- 203 response content: diff --git a/examples/v3.0/petstore-expanded.yaml b/examples/v3.0/petstore-expanded.yaml index f587075899..6c6195199c 100644 --- a/examples/v3.0/petstore-expanded.yaml +++ b/examples/v3.0/petstore-expanded.yaml @@ -40,7 +40,7 @@ paths: type: integer format: int32 responses: - 200: + '200': description: pet response content: application/json: @@ -65,7 +65,7 @@ paths: schema: $ref: '#/components/schemas/NewPet' responses: - 200: + '200': description: pet response content: application/json: @@ -90,7 +90,7 @@ paths: type: integer format: int64 responses: - 200: + '200': description: pet response content: application/json: @@ -114,7 +114,7 @@ paths: type: integer format: int64 responses: - 204: + '204': description: pet deleted default: description: unexpected error diff --git a/examples/v3.0/petstore.yaml b/examples/v3.0/petstore.yaml index b444f02531..5fdfba907d 100644 --- a/examples/v3.0/petstore.yaml +++ b/examples/v3.0/petstore.yaml @@ -22,7 +22,7 @@ paths: type: integer format: int32 responses: - 200: + '200': description: An paged array of pets headers: x-next: @@ -45,7 +45,7 @@ paths: tags: - pets responses: - 201: + '201': description: Null response default: description: unexpected error @@ -67,7 +67,7 @@ paths: schema: type: string responses: - 200: + '200': description: Expected response to a valid request content: application/json: diff --git a/examples/v3.0/uber.yaml b/examples/v3.0/uber.yaml index 2c77b440f9..735b8c8ed0 100644 --- a/examples/v3.0/uber.yaml +++ b/examples/v3.0/uber.yaml @@ -32,7 +32,7 @@ paths: tags: - Products responses: - 200: + "200": description: An array of products content: application/json: @@ -80,7 +80,7 @@ paths: tags: - Estimates responses: - 200: + "200": description: An array of price estimates by product content: application/json: @@ -127,7 +127,7 @@ paths: tags: - Estimates responses: - 200: + "200": description: An array of products content: application/json: @@ -148,7 +148,7 @@ paths: tags: - User responses: - 200: + "200": description: Profile information for a user content: application/json: @@ -180,7 +180,7 @@ paths: tags: - User responses: - 200: + "200": description: History information for the given user content: application/json: From 19a0cb3c38e63c8e1576d4d6960443a8a567b190 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 4 Aug 2017 09:46:59 +0100 Subject: [PATCH 02/12] Update heading text of IMPLEMENTATIONS.md --- IMPLEMENTATIONS.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/IMPLEMENTATIONS.md b/IMPLEMENTATIONS.md index 5bcfc85245..09e622462b 100644 --- a/IMPLEMENTATIONS.md +++ b/IMPLEMENTATIONS.md @@ -1,10 +1,6 @@ ### Implementations -Below is a list of known tooling that implements the 3.0.0 specification. Because -the 3.0.0 specification has not yet been released, refer to the details of projects listed below for any notes about stability and roadmap. The process -to create the best possible 3.0.0 specification includes feedback from end-users -and tooling creators. We strongly encourage draft tooling be -made available for early users of the OAS. +Below is a list of known tooling that implements the 3.0.0 specification. While support for the 3.0.0 specification matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the 3.x specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts. These tools are not necessarily endorsed by the OAI. From 093f8f718a364fbd1cdcbd0988582019557e6fd0 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 18 Aug 2017 16:17:13 +0200 Subject: [PATCH 03/12] [IMPLEMENTATIONS] Add odata-openapi Add OData-to-OpenAPI converter to the list of low-level tools --- IMPLEMENTATIONS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/IMPLEMENTATIONS.md b/IMPLEMENTATIONS.md index 5bcfc85245..c815fcb6cf 100644 --- a/IMPLEMENTATIONS.md +++ b/IMPLEMENTATIONS.md @@ -18,6 +18,7 @@ These tools are not necessarily endorsed by the OAI. | openapi3-ts | [GitHub/metadevpro/openapi3-ts](https://github.com/metadevpro/openapi3-ts) | TypeScript | TS Model & utils for OpenAPI 3.0.x contracts | | swagger2openapi | [GitHub/mermade/swagger2openapi](https://github.com/mermade/swagger2openapi) | Node.js | An OpenAPI / Swagger 2.0 to OpenAPI 3.0.x converter and validator | | Tavis.OpenApi | [GitHub/tavis-sofware/Tavis.OpenApi](https://github.com/tavis-software/Tavis.OpenApi/) | dotnet | C# based parser with definition validation and migration support from V2 | +| odata-openapi | [GitHub/oasis-tcs/odata-openapi](https://github.com/oasis-tcs/odata-openapi) | XSLT | OData 4.0 to OpenAPI 3.0.0 converter | #### Editors From 32eada766caaaab9b8211e2b02ede01057d22df1 Mon Sep 17 00:00:00 2001 From: Ron Date: Mon, 21 Aug 2017 11:55:52 -0700 Subject: [PATCH 04/12] updated development guidelines --- DEVELOPMENT.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index d5f6fff76b..e4a2bd29fb 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,6 +1,6 @@ ## Development Guidelines -This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Contributor Board will initially follow these processes when merging changes from external contributors or from the TCB itself. This guideline document will be adjusted as practicality dictates. +This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Developer Community will initially follow these processes when merging changes from external contributors or from the TDC itself. This guideline document will be adjusted as practicality dictates. ## OAI Specification Driving factors @@ -21,14 +21,19 @@ The specification _will change_ from the original 2.0 version. We should typica - Use GitHub for all spec designs, use cases, and so on. - As with 2.0, the **human readable** document is the source of truth. If using a JSON Schema again to document the spec, it is secondary to the human documentation. The documentation should live in a *.md file, in parallel to the 2.0 document (versions/3.0.0.md for example). - - The `master` branch shall remain the current, released OpenAPI Specification (i.e., 2.0). We will work in an OpenAPI.next branch, which shall be described and linked to on the **default** README.md on master. + - At any given time, there would be _at most_ 4 work branches. The branches would exist if work has started on them. Assuming a current version of 3.0.0: + - `master` - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. + - `v3.0.1` - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. + - `v3.1.0` - The naxt MINOR version. + - `v4.0.0` - The next MAJOR version. + - The `master` branch shall remain the current, released OpenAPI Specification. We will describe and link the work branch(es) on the **default** README.md on master. - Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. - - New features should be done in feature branches which, upon approval, are merged into the OpenAPI.next branch. + - New features should be done in feature branches/forks which, upon approval, are merged into the proper work branch. - Use labels for the workflow of specification changes. Examples of labels are `proposed`, `needs migration review`, `needs tooling review`, `needs documentation`, `rejected`, and `needs approval`. These labels must be assigned by project committers. - An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change. - A PR will be used to describe the _proposed_ solution, and linked to the original issue. - Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel. - - When the OpenApi.next spec is complete and approved for release, the branch will be merged to master. + - When the a work branch is ready and approved, the branch will be merged to master. ## Approving Changes From dc6ddf320800d31e5207305edce3747d32dbf196 Mon Sep 17 00:00:00 2001 From: Ron Date: Mon, 21 Aug 2017 11:59:16 -0700 Subject: [PATCH 05/12] Link to the next version --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 7eaf9ba26d..f2f1f82cd4 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,10 @@ Here you will find the information you need about the OpenAPI Specification, sim The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.0.md). +### Future Versions + +[3.0.1](https://github.com/OAI/OpenAPI-Specification/tree/v3.0.1) - The next PATCH version. Patch-level fixes (typos, clarifications, etc.) should be submitted against this branch. + ### Previous Versions This repository also contains the [OpenAPI Specification 2.0](versions/2.0.md), which is identical to the Swagger 2.0 specification before it was renamed to “OpenAPI Specification”, From 67ce0be9541ec94fa7eb232a6fbf9958d8018249 Mon Sep 17 00:00:00 2001 From: Darrel Date: Mon, 21 Aug 2017 15:14:15 -0400 Subject: [PATCH 06/12] Fixed typo --- DEVELOPMENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index e4a2bd29fb..698eccfb69 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -24,7 +24,7 @@ The specification _will change_ from the original 2.0 version. We should typica - At any given time, there would be _at most_ 4 work branches. The branches would exist if work has started on them. Assuming a current version of 3.0.0: - `master` - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. - `v3.0.1` - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. - - `v3.1.0` - The naxt MINOR version. + - `v3.1.0` - The next MINOR version. - `v4.0.0` - The next MAJOR version. - The `master` branch shall remain the current, released OpenAPI Specification. We will describe and link the work branch(es) on the **default** README.md on master. - Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. From 70cedc9ead883ebb8d639c4eb7759065313722b6 Mon Sep 17 00:00:00 2001 From: Brendan Abbott Date: Fri, 14 Jul 2017 17:57:10 +1000 Subject: [PATCH 07/12] Add lincoln and serverless-openapi-documentation projects to the IMPLEMENTATIONS.md --- IMPLEMENTATIONS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/IMPLEMENTATIONS.md b/IMPLEMENTATIONS.md index fcd8296140..96a2a2d6c1 100644 --- a/IMPLEMENTATIONS.md +++ b/IMPLEMENTATIONS.md @@ -32,6 +32,7 @@ These tools are not necessarily endorsed by the OAI. |----------------|--------------|----------|---------------------| | openapi-viewer | [GitHub/koumoul/openapi-viewer](https://github.com/koumoul-dev/openapi-viewer) | Vue.js | Browse and test a REST API described with the OpenAPI 3.0 Specification. | | swagger-ui | [GitHub/swagger-api](https://github.com/swagger-api/swagger-UI) | JavaScript | Web-Based interface for visualizing and testing OpenAPI\Swagger definitions | +| lincoln | [GitHub/temando/open-api-renderer](https://github.com/temando/open-api-renderer)| React.js| A React renderer for Open API v3 | #### Server Implementations @@ -43,3 +44,4 @@ These tools are not necessarily endorsed by the OAI. |----------------|--------------|----------|---------------------| | baucis-openapi3 | [Github/metadevpro/baucis-openapi3](https://github.com/metadevpro/baucis-openapi3) | Node.js | [Baucis.js](https://github.com/wprl/baucis) plugin for generating OpenAPI 3.0 compliant API contracts. | | Google Gnostic | [GitHub/googleapis/gnostic](https://github.com/googleapis/gnostic) | Go | Compile OpenAPI descriptions into equivalent Protocol Buffer representations. | +| serverless-openapi-documentation | [GitHub/temando/serverless-openapi-documentation](https://github.com/temando/serverless-openapi-documentation) | Typescript | Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration | From f75f8486a1aae1a7ceef92fbc63692cb2556c0cd Mon Sep 17 00:00:00 2001 From: Helen Kosova Date: Tue, 22 Aug 2017 19:28:49 +0300 Subject: [PATCH 08/12] Change response code quoting style from " to ' for consistency --- examples/v3.0/api-with-examples.yaml | 8 ++++---- examples/v3.0/uber.yaml | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index ae491420e5..dd42b0e959 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -8,7 +8,7 @@ paths: operationId: listVersionsv2 summary: List API versions responses: - "200": + '200': description: |- 200 response content: @@ -41,7 +41,7 @@ paths: } ] } - "300": + '300': description: |- 300 response content: @@ -80,7 +80,7 @@ paths: operationId: getVersionDetailsv2 summary: Show API version details responses: - "200": + '200': description: |- 200 response content: @@ -125,7 +125,7 @@ paths: ] } } - "203": + '203': description: |- 203 response content: diff --git a/examples/v3.0/uber.yaml b/examples/v3.0/uber.yaml index 735b8c8ed0..8b94db300f 100644 --- a/examples/v3.0/uber.yaml +++ b/examples/v3.0/uber.yaml @@ -32,7 +32,7 @@ paths: tags: - Products responses: - "200": + '200': description: An array of products content: application/json: @@ -80,7 +80,7 @@ paths: tags: - Estimates responses: - "200": + '200': description: An array of price estimates by product content: application/json: @@ -127,7 +127,7 @@ paths: tags: - Estimates responses: - "200": + '200': description: An array of products content: application/json: @@ -148,7 +148,7 @@ paths: tags: - User responses: - "200": + '200': description: Profile information for a user content: application/json: @@ -180,7 +180,7 @@ paths: tags: - User responses: - "200": + '200': description: History information for the given user content: application/json: From 88cd94419e117b154b67b834fa8e471bb98bd346 Mon Sep 17 00:00:00 2001 From: Christophe Vidal Date: Sun, 27 Aug 2017 23:06:51 +0700 Subject: [PATCH 09/12] Fixed JSON Schema description for ResponsesDefinitions --- schemas/v2.0/schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/v2.0/schema.json b/schemas/v2.0/schema.json index f12a8c0e47..a92e18f2a5 100644 --- a/schemas/v2.0/schema.json +++ b/schemas/v2.0/schema.json @@ -203,7 +203,7 @@ "additionalProperties": { "$ref": "#/definitions/response" }, - "description": "One or more JSON representations for parameters" + "description": "One or more JSON representations for responses" }, "externalDocs": { "type": "object", From fe0975d4922f92d971460f411e274b83b4e9a139 Mon Sep 17 00:00:00 2001 From: maverickelementalch Date: Fri, 13 Oct 2017 12:30:45 +0200 Subject: [PATCH 10/12] Update version in description to OpenAPI 3.0 --- examples/v3.0/petstore-expanded.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/v3.0/petstore-expanded.yaml b/examples/v3.0/petstore-expanded.yaml index 6c6195199c..e8c0fe5ffd 100644 --- a/examples/v3.0/petstore-expanded.yaml +++ b/examples/v3.0/petstore-expanded.yaml @@ -2,7 +2,7 @@ openapi: "3.0.0" info: version: 1.0.0 title: Swagger Petstore - description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification + description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification termsOfService: http://swagger.io/terms/ contact: name: Swagger API Team From 35210824bda34bb8f5e3b2814a2c0cfbb6a7814b Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Tue, 17 Oct 2017 08:52:20 -0700 Subject: [PATCH 11/12] Describe governance of TSC per #1358 --- GOVERNANCE.MD | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 GOVERNANCE.MD diff --git a/GOVERNANCE.MD b/GOVERNANCE.MD new file mode 100644 index 0000000000..982104b394 --- /dev/null +++ b/GOVERNANCE.MD @@ -0,0 +1,31 @@ +# Governance + +The OpenAPI Specification is a project of the Open API Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance). + +# Processes and procedures of the Technical Steering Committee (TSC) + +The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines. + +## 1. The establishment of roles and the responsibilities for each role + +Roles: + +* [Liaison](https://www.merriam-webster.com/dictionary/liaison) — Elected by TSC members in a plurality vote (oral count). Liaison represents the TSC to the BGB at board meetings (though this itself does not confer voting rights) and is the public facing mouthpiece of the TSC. + +* [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible from approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. + +* [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members. + +## 2. Adding members to the TSC + +At an open TDC meeting, the impending call-for-nominations period is communicated and subsequently tweeted, no more than once per quarter. Nominations for members happen at closed TSC meetings via a motion by a voting TSC member. A nominee must not receive negative votes from 25% or more of the TSC voting membership. in a confidential vote held electronically within a week of the nomination. Approved nominees are expected to comport themselves during the provisional period of four weeks as full members of the TSC, though nominees do not have voting rights until their membership is confirmed. TSC subsequently votes on those nominees in the subsequent TSC meeting. At most there are four voting periods per year, with a minimum of 1 per year. + +## 3. Removal of membership from the TSC + +In dire situations, it may be necessary to remove a TSC member, such as behavior that violates the code of conduct (whether non-participation merits removal is a decision left to the TSC voting members). 75% vote (confidential, electronic) of the other TSC. members is required to remove a member. Otherwise, TSC members are removed when they renounce their position. + +## 4. Criteria for decisions + +The group will strive to achieve all decisions via unopposed consensus. When not possible, unresolved conflicts will be raised to the TOB. + +The TSC will maintain a publicly available document specifying the process in the contributor guidelines for how proposed changes are merged into the specification. The TSC will document and publicize the schedule of merge parties and release parties for the benefit of the technical developer community. From a27ba381580eeb36558cedafd22d3e3b8e5f6bcc Mon Sep 17 00:00:00 2001 From: Bert Roos Date: Thu, 19 Oct 2017 14:30:20 +0200 Subject: [PATCH 12/12] Correct comment on the link object The example referencing the response body had the same comment as the one referencing the request path. --- versions/3.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 30a041ad84..93f55b323a 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -2051,7 +2051,7 @@ links: address: operationId: getUserAddressByUUID parameters: - # get the `id` field from the request path parameter named `id` + # get the `uuid` field from the `uuid` field in the response body userUuid: $response.body#/uuid ```