diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index d5f6fff76b..698eccfb69 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 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. - - 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 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. diff --git a/IMPLEMENTATIONS.md b/IMPLEMENTATIONS.md index 5bcfc85245..96a2a2d6c1 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. @@ -18,6 +14,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 @@ -35,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 @@ -46,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 | 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”, diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 8fdee415ad..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/petstore-expanded.yaml b/examples/v3.0/petstore-expanded.yaml index f587075899..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 @@ -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..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: 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", 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 ```