From 76f184b5e7aa8bce1b1d2d3600a2649b4619af54 Mon Sep 17 00:00:00 2001 From: Alasdair Hurst Date: Tue, 25 Feb 2020 15:08:31 +0000 Subject: [PATCH 01/76] #2157: Update schema to validate refs in headers of encoding objects --- schemas/v3.0/schema.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/schemas/v3.0/schema.yaml b/schemas/v3.0/schema.yaml index 13e47ff08d..b19f0a9669 100644 --- a/schemas/v3.0/schema.yaml +++ b/schemas/v3.0/schema.yaml @@ -1,4 +1,4 @@ -id: https://spec.openapis.org/oas/3.0/schema/2019-04-02 +id: https://spec.openapis.org/oas/3.0/schema/2020-02-25 $schema: http://json-schema.org/draft-04/schema# description: Validation schema for OpenAPI Specification 3.0.X. type: object @@ -987,7 +987,9 @@ definitions: headers: type: object additionalProperties: - $ref: '#/definitions/Header' + oneOf: + - $ref: '#/definitions/Header' + - $ref: '#/definitions/Reference' style: type: string enum: From 54b0264dbdb018f3f1166872c73a0d5bd6786d27 Mon Sep 17 00:00:00 2001 From: Sami Akkawi <45228655+SamiAkkawi@users.noreply.github.com> Date: Thu, 15 Apr 2021 19:02:49 +0200 Subject: [PATCH 02/76] servers is an array of server (#2526) * servers is an array of server * fix only yaml file * add servers test * update schema.json from shema.yaml --- schemas/v3.1/schema.json | 7 +++++-- schemas/v3.1/schema.yaml | 4 +++- tests/v3.1/fail/servers.yaml | 8 ++++++++ tests/v3.1/pass/servers.yaml | 10 ++++++++++ 4 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 tests/v3.1/fail/servers.yaml create mode 100644 tests/v3.1/pass/servers.yaml diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index fa987c12d6..e1e859dbe3 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -15,7 +15,10 @@ "default": "https://spec.openapis.org/oas/3.1/dialect/base" }, "servers": { - "$ref": "#/$defs/server" + "type": "array", + "items": { + "$ref": "#/$defs/server" + } }, "paths": { "$ref": "#/$defs/paths" @@ -1337,4 +1340,4 @@ } } } -} +} \ No newline at end of file diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 9b71e11031..60377ae424 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -12,7 +12,9 @@ properties: $ref: '#/$defs/uri' default: 'https://spec.openapis.org/oas/3.1/dialect/base' servers: - $ref: '#/$defs/server' + type: array + items: + $ref: '#/$defs/server' paths: $ref: '#/$defs/paths' webhooks: diff --git a/tests/v3.1/fail/servers.yaml b/tests/v3.1/fail/servers.yaml new file mode 100644 index 0000000000..7aaa05c0af --- /dev/null +++ b/tests/v3.1/fail/servers.yaml @@ -0,0 +1,8 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: {} +servers: + url: /v1 + description: Run locally. diff --git a/tests/v3.1/pass/servers.yaml b/tests/v3.1/pass/servers.yaml new file mode 100644 index 0000000000..77a20498da --- /dev/null +++ b/tests/v3.1/pass/servers.yaml @@ -0,0 +1,10 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: {} +servers: + - url: /v1 + description: Run locally. + - url: https://production.com/v1 + description: Run on production server. From 9092530007cbc8edabd121523061eba9d62b7716 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Wed, 7 Apr 2021 12:14:19 -0700 Subject: [PATCH 03/76] Add "put" to allowed property name for PathItem in 3.1 schema --- schemas/v3.1/schema.json | 4 ++-- schemas/v3.1/schema.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index e1e859dbe3..fc6ff147a7 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -304,7 +304,7 @@ } }, "patternProperties": { - "^(get|post|delete|options|head|patch|trace)$": { + "^(get|put|post|delete|options|head|patch|trace)$": { "$ref": "#/$defs/operation" } }, @@ -1340,4 +1340,4 @@ } } } -} \ No newline at end of file +} diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 60377ae424..a4c1e7e109 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -209,7 +209,7 @@ $defs: items: $ref: '#/$defs/parameter-or-reference' patternProperties: - '^(get|post|delete|options|head|patch|trace)$': + '^(get|put|post|delete|options|head|patch|trace)$': $ref: '#/$defs/operation' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false From 08d22f6f712fcc79f819bd5cb3fb394b89cfddce Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 15 Apr 2021 09:32:07 -0700 Subject: [PATCH 04/76] Update $id for release --- schemas/v3.1/schema-base.json | 4 ++-- schemas/v3.1/schema-base.yaml | 4 ++-- schemas/v3.1/schema.json | 2 +- schemas/v3.1/schema.yaml | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json index 078af184fe..658e943cc5 100644 --- a/schemas/v3.1/schema-base.json +++ b/schemas/v3.1/schema-base.json @@ -1,7 +1,7 @@ { - "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-03-02", + "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-04-15", "$schema": "https://json-schema.org/draft/2020-12/schema", - "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", "properties": { "jsonSchemaDialect": { "$ref": "#/$defs/dialect" diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml index 41a27be7a9..515ed08989 100644 --- a/schemas/v3.1/schema-base.yaml +++ b/schemas/v3.1/schema-base.yaml @@ -1,7 +1,7 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-03-02' +$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-04-15' $schema: 'https://json-schema.org/draft/2020-12/schema' -$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' properties: jsonSchemaDialect: $ref: '#/$defs/dialect' diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index fc6ff147a7..a798834247 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -1,5 +1,5 @@ { - "$id": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + "$id": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index a4c1e7e109..86cb44efca 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -1,4 +1,4 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +$id: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' $schema: 'https://json-schema.org/draft/2020-12/schema' type: object From 5b55a134bcf7aa50b9e54704d3df979e17f25d19 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Sun, 18 Apr 2021 17:20:14 +0100 Subject: [PATCH 05/76] fix: update refs to master branch to main (#2546) Signed-off-by: Mike Ralphson --- .github/workflows/convert-examples-to-json.yaml | 9 ++++----- .github/workflows/validate-markdown.yaml | 2 +- DEVELOPMENT.md | 8 ++++---- README.md | 4 ++-- guidelines/v2.0/REUSE.md | 6 +++--- proposals/000_OAS-proposal-template.md | 4 ++-- proposals/001_Alternative Schema Proposal.md | 10 +++++----- proposals/002_Webhooks.md | 2 +- proposals/003_Clarify-Nullable.md | 2 +- proposals/004_Overlays.md | 2 +- proposals/Alternative Schema/schema_object.md | 6 +++--- 11 files changed, 27 insertions(+), 28 deletions(-) diff --git a/.github/workflows/convert-examples-to-json.yaml b/.github/workflows/convert-examples-to-json.yaml index 2ed4ca865e..8cc63f5398 100644 --- a/.github/workflows/convert-examples-to-json.yaml +++ b/.github/workflows/convert-examples-to-json.yaml @@ -10,11 +10,11 @@ name: convert-examples-to-json # Only the YAML files should be adjusted manually. # -# run this on push to master +# run this on push to main on: push: branches: - - master + - main jobs: yaml2json: @@ -22,7 +22,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 # checkout repo content + - uses: actions/checkout@v2 # checkout repo content - name: Install dependencies run: npm i @@ -36,10 +36,9 @@ jobs: git --no-pager -c color.diff=always diff --staged - name: Create Pull Request - uses: peter-evans/create-pull-request@v1 + uses: peter-evans/create-pull-request@v3 with: token: ${{ secrets.GITHUB_TOKEN }} - branch-suffix: none branch: update-json-examples title: Update JSON example files commit-message: Update JSON example files diff --git a/.github/workflows/validate-markdown.yaml b/.github/workflows/validate-markdown.yaml index a127677452..05af39ceaf 100644 --- a/.github/workflows/validate-markdown.yaml +++ b/.github/workflows/validate-markdown.yaml @@ -18,7 +18,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 # checkout repo content + - uses: actions/checkout@v2 # checkout repo content - uses: actions/setup-node@v1 # setup Node.js with: node-version: '12.x' diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8a768b3d1c..6b8fc56e87 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -40,7 +40,7 @@ Spec changes should be approved by a majority of the committers. Approval can be * 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. + * main - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. * v3.0.1-dev - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. @@ -48,7 +48,7 @@ Spec changes should be approved by a majority of the committers. Approval can be * 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. +* The main branch shall remain the current, released OpenAPI Specification. We will describe and link the work branch(es) on the **default** README.md on main. * Examples of how something is described *currently* vs. the proposed solution should accompany any change proposal. @@ -62,11 +62,11 @@ Spec changes should be approved by a majority of the committers. Approval can be * 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 work branch is ready and approved, the branch will be merged to master. +* When the work branch is ready and approved, the branch will be merged to main. ## Release Process -A release requires a vote on the release notes by TSC members within the voting period. Major or minor release voting periods will be announced by the Liaison in the Slack channel and noted on the calendar at least 6 days in advance. During this time, TSC members who have not yet voted must note their approval on the GitHub pull request for the release notes. Patch releases happen at the first TSC meeting of a calendar month. The Liaison is responsible for coordinating the actual merge to Master with marketing support, if any. +A release requires a vote on the release notes by TSC members within the voting period. Major or minor release voting periods will be announced by the Liaison in the Slack channel and noted on the calendar at least 6 days in advance. During this time, TSC members who have not yet voted must note their approval on the GitHub pull request for the release notes. Patch releases happen at the first TSC meeting of a calendar month. The Liaison is responsible for coordinating the actual merge to main with marketing support, if any. * Patch-level releases require majority approval by TSC members. (Max voting period 3 days) diff --git a/README.md b/README.md index 0a81ca7f21..9c399250a5 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Looking to see how you can create your own OpenAPI definition, present it, or ot The current process for development of the OpenAPI Specification is described in [Development Guidelines](DEVELOPMENT.md). -Development of the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master. +Development of the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to `main`. The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the [TSC calendar online](https://openapi.groups.io/g/tsc/calendar), and import it to your calendar using the [iCal link](https://openapi.groups.io/g/tsc/ics/1105671/1995679554/feed.ics). @@ -53,6 +53,6 @@ Not all feedback can be accommodated and there may be solid arguments for or aga ## Licensing -See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/master/LICENSE) +See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE) ![Analytics](https://ga-beacon.appspot.com/UA-831873-42/readme.md?pixel) diff --git a/guidelines/v2.0/REUSE.md b/guidelines/v2.0/REUSE.md index 2d3192c262..60975c484a 100644 --- a/guidelines/v2.0/REUSE.md +++ b/guidelines/v2.0/REUSE.md @@ -81,7 +81,7 @@ When referencing locally (within the current document), the target references sh An example of a local definition reference: -_Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json_ +_Example from https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v2.0/json/petstore.json_ ``` json // ... "200": { @@ -100,7 +100,7 @@ _Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/ Files can be referred to in relative paths to the current document. -_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ +_Example from https://github.com/OAI/OpenAPI-Specification/tree/main/examples/v2.0/json/petstore-separate/spec/swagger.json_ ``` json // ... @@ -116,7 +116,7 @@ _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/ Remote references may also reference properties within the relative remote file. -_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ +_Example from https://github.com/OAI/OpenAPI-Specification/tree/main/examples/v2.0/json/petstore-separate/spec/swagger.json_ ``` json // ... "parameters": [ diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md index da2a8b1eeb..799c73b491 100644 --- a/proposals/000_OAS-proposal-template.md +++ b/proposals/000_OAS-proposal-template.md @@ -5,11 +5,11 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})| +|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{directory_or_file_name})| |Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})| |Review Manager |TBD | |Status |Proposal, Draft, Promoted, or Abandoned| -|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)| +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{NNNN}/implementations.md)| |Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})| |Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 9f176ea28e..a0faab8c06 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -4,11 +4,11 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| +|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema)| |Authors|[Chuck Heazel](https://github.com/{cmheazel})| |Review Manager |TBD | |Status |**Draft** | -|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/implementations.md) +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema/implementations.md) |Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)| |Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) | @@ -42,14 +42,14 @@ This proposal makes the following changes to the OAS 3.0 specification: ### Extend the Schema Object -The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/schema_object.md) +The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema/schema_object.md) ### Add the Alternative Schema Object -The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_object.md) +The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema/alternative_schema_object.md) ### Provide Alternative Schema Examples -Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_examples.md) +Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema/alternative_schema_examples.md) ### Alternative Schema Registry diff --git a/proposals/002_Webhooks.md b/proposals/002_Webhooks.md index 8ad8a97fa9..3daf5aadff 100644 --- a/proposals/002_Webhooks.md +++ b/proposals/002_Webhooks.md @@ -5,7 +5,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/002_webhooks.md)| +|Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/002_webhooks.md)| |Authors|[Lorna Mitchell](https://github.com/lornajane)| |Review Manager |TBD | |Status |Proposal| diff --git a/proposals/003_Clarify-Nullable.md b/proposals/003_Clarify-Nullable.md index 139b0dceef..7e82c7b6ca 100644 --- a/proposals/003_Clarify-Nullable.md +++ b/proposals/003_Clarify-Nullable.md @@ -5,7 +5,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[003](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/003_Clarify-Nullable.md)| +|Proposal |[003](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/003_Clarify-Nullable.md)| |Authors|[Ted Epstein](https://github.com/tedepstein)| |Review Manager |TBD| |Status |Proposal| diff --git a/proposals/004_Overlays.md b/proposals/004_Overlays.md index de820558ba..4c352804c0 100644 --- a/proposals/004_Overlays.md +++ b/proposals/004_Overlays.md @@ -4,7 +4,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/004_overlays.md)| +|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/004_overlays.md)| |Authors|[Darrel Miller](https://github.com/darrelmiller)| |Status |Proposal| |Issues |[1442](https://github.com/OAI/OpenAPI-Specification/issues/1442) [1722](https://github.com/OAI/OpenAPI-Specification/issues/1722)| diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative Schema/schema_object.md index df8c64c8ff..7d9f57ecdd 100644 --- a/proposals/Alternative Schema/schema_object.md +++ b/proposals/Alternative Schema/schema_object.md @@ -7,11 +7,11 @@ The following content shall be used to replace the Fixed Fields table in the Sch |Field Name | Type | Description | |---|:---:|---| | nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.| -| discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaComposition) for more details. | +| discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#schemaComposition) for more details. | | readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | | writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | -| xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | -| externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema. +| xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | +| externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema. | example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.| | deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.| |x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | From 912498eba3a559e74bb546b04d687e8e46d59c86 Mon Sep 17 00:00:00 2001 From: Neal Caidin Date: Mon, 26 Apr 2021 10:20:09 -0400 Subject: [PATCH 06/76] Update TOB.md The election cycle for 2021 is complete and the existing TSC-elected members have agreed to serve another term. No additional nominations were received. --- TOB.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOB.md b/TOB.md index 0a6f6f2868..c40deee81d 100644 --- a/TOB.md +++ b/TOB.md @@ -3,7 +3,7 @@ ## Description: > The TOB is responsible for managing conflicts, violations of procedures or guidelines or other issues that cannot be resolved in the TSC for the OAS. For further details please consult the OpenAPI Project Charter. -## TSC Elected - terms through May 2021 +## TSC Elected - terms through May 2023 Isabelle Mauny @isamauny Uri Sarid @usarid From a295d9af0e64ba9b9d0cbbc2c6f63f1bf2e967d5 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 20 May 2021 17:38:59 +0100 Subject: [PATCH 07/76] feat: add agenda workflow/template (#2571) Signed-off-by: Mike Ralphson --- .github/templates/agenda.md | 19 +++++++++++++++++++ .github/workflows/agenda.yaml | 29 +++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 .github/templates/agenda.md create mode 100644 .github/workflows/agenda.yaml diff --git a/.github/templates/agenda.md b/.github/templates/agenda.md new file mode 100644 index 0000000000..590983c7ef --- /dev/null +++ b/.github/templates/agenda.md @@ -0,0 +1,19 @@ +**NOTE: This meeting is on Thursday at 9am - 10am PT** + +Zoom Meeting link: [https://zoom.us/j/975841675](https://zoom.us/j/975841675?pwd=SUh4MjRLaEFKNlI3RElpWTdhRDVVUT09). Dial-in passcode: 763054 + +In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics. + +**Please submit comments below for topics or proposals that you wish to present in the TDC meeting** + +The agenda backlog is currently maintained in issue #2482 + +| Topic | Owner | Decision/NextStep | +|-------|---------|---------| +| | | | +AOB (see below) | TDC | | +New issues / PRs labelled [review](https://github.com/OAI/OpenAPI-Specification/labels/review) | @OAI/triage | | +[New issues](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) without response yet | @OAI/triage | | + + +/cc @OAI/tsc Please suggest items for inclusion diff --git a/.github/workflows/agenda.yaml b/.github/workflows/agenda.yaml new file mode 100644 index 0000000000..d9c347ef31 --- /dev/null +++ b/.github/workflows/agenda.yaml @@ -0,0 +1,29 @@ +name: agenda + +# author: @MikeRalphson +# issue: various + +# +# This workflow creates the agenda issue each week. It runs on a cron every +# Monday morning, raising an issue for the following Thursday. +# It can also be run manually, in case GitHub Actions has a failure. +# + +on: + schedule: + - cron: '0 9 * * 2' + workflow_dispatch: {} + +jobs: + agenda: + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v1 # checkout repo content + + - name: Create agenda issue + run: gh issue create -l Housekeeping -t "Open Community (TDC) Meeting, `date --date='next Thu' +'%A %d %B %Y'`" -F .github/templates/agenda.md + From cc45c37d69048993db05e03a28fb7331c0697ad5 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 20 May 2021 17:42:25 +0100 Subject: [PATCH 08/76] Add script and GitHub action to automatically generate ReSpec versions of the spec (#2574) * workflows: update used actions * . * bikeshed rendering (WIP) * bikeshed; split into v2, v3 directories * bikeshed; fixes to TOC,code blocks and indent levels * bikeshed; work from unmodified .md files * bikeshed; .gitignore * bikeshed; separate header for v3.0.1 for now * respec; as an alternative to bikeshed * Rename bikeshed to md2html * md2html; current setup * md2html; wip * md2html; fix 1 toc bug * md2html; fix another toc bug * md2html; fix 1 respec toc bug * md2html; fix another bikeshed toc bug * respec; former editor support - needs ReSpec 20.x * Latest respec tweaks * pre block css background, RFC ref fixes * Github gist syntax highlighting css * md2html: move to scripts dir * md2html: resolve relative links for examples * md2html: use respec js from spec.openapis.org site * md2html: find gist.css regardless of run dir * md2html: don't mix https and http content (toc) * md2html; include google analytics * md2html; build putative versions 4,5 etc * md2html; tidying up * md2html; specify lang="en" in html * build: update deps * fix: style examples bugs, refs #2488 * fix: update highlightjs call in md2html * feat: add github action Signed-off-by: Mike Ralphson * build: create a `latest.html` ReSpec version Signed-off-by: Mike Ralphson --- .github/workflows/respec.yaml | 55 +++++ .gitignore | 2 + package.json | 7 +- scripts/md2html/.gitignore | 2 + scripts/md2html/analytics/google.html | 8 + scripts/md2html/build.sh | 27 +++ scripts/md2html/gist.css | 71 ++++++ scripts/md2html/md2html.js | 310 ++++++++++++++++++++++++++ scripts/md2html/style-finish.html | 1 + scripts/md2html/style-start.html | 5 + scripts/md2html/syntax-github.css | 99 ++++++++ 11 files changed, 586 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/respec.yaml create mode 100644 scripts/md2html/.gitignore create mode 100644 scripts/md2html/analytics/google.html create mode 100755 scripts/md2html/build.sh create mode 100644 scripts/md2html/gist.css create mode 100644 scripts/md2html/md2html.js create mode 100644 scripts/md2html/style-finish.html create mode 100644 scripts/md2html/style-start.html create mode 100644 scripts/md2html/syntax-github.css diff --git a/.github/workflows/respec.yaml b/.github/workflows/respec.yaml new file mode 100644 index 0000000000..bfa286f72e --- /dev/null +++ b/.github/workflows/respec.yaml @@ -0,0 +1,55 @@ +name: respec + +# author: @MikeRalphson +# issue: https://github.com/OAI/OpenAPI-Specification/issues/1564 + +# +# This workflow updates the respec 'pretty' rendered versions of the spec +# on the gh-pages branch when the corresponding markdown files change. +# + +# run this on push to main +on: + push: + branches: + - main + workflow_dispatch: {} + +jobs: + respec: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 # checkout main branch + + - name: Install dependencies + run: npm i + + - uses: actions/checkout@v2 # checkout gh-pages branch + with: + ref: gh-pages + path: deploy + + - name: run main script + run: scripts/md2html/build.sh + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: update-respec-version + base: gh-pages + delete-branch: true + path: deploy + labels: Housekeeping + reviewers: webron,darrelmiller + title: Update ReSpec versions + commit-message: Update ReSpec versions + signoff: true + body: | + This pull request is automatically triggered by GitHub action `respec`. + + The versions/v*.md files have changed, so the HTML files are automatically being regenerated. + + diff --git a/.gitignore b/.gitignore index aa8e47b4c6..9ffeae3497 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,6 @@ target atlassian-ide-plugin.xml node_modules/ package-lock.json +deploy/ +history Gemfile.lock diff --git a/package.json b/package.json index 59851cb7dc..ac2cac61d3 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,12 @@ "README.md", "schemas/*" ], - "dependencies": {}, + "dependencies": { + "cheerio": "^1.0.0-rc.5", + "highlight.js": "^10.6.0", + "markdown-it": "^12.0.4", + "yargs": "^12.0.5" + }, "devDependencies": { "@hyperjump/json-schema": "^0.17.0", "chai": "^4.3.1", diff --git a/scripts/md2html/.gitignore b/scripts/md2html/.gitignore new file mode 100644 index 0000000000..12516577e2 --- /dev/null +++ b/scripts/md2html/.gitignore @@ -0,0 +1,2 @@ +*.err +input.bs diff --git a/scripts/md2html/analytics/google.html b/scripts/md2html/analytics/google.html new file mode 100644 index 0000000000..dce8d08cf4 --- /dev/null +++ b/scripts/md2html/analytics/google.html @@ -0,0 +1,8 @@ + + + diff --git a/scripts/md2html/build.sh b/scripts/md2html/build.sh new file mode 100755 index 0000000000..3ddf387c2e --- /dev/null +++ b/scripts/md2html/build.sh @@ -0,0 +1,27 @@ +#!/bin/sh + +# run this script from the root of the repo + +mkdir -p deploy/oas +mkdir -p deploy/js + +cd scripts/md2html +mkdir -p history +git show c740e950d:MAINTAINERS.md > history/MAINTAINERS_v2.0.md +cp -p js/* ../../deploy/js 2> /dev/null +cp -p markdown/* ../../deploy/ 2> /dev/null + +node md2html.js --respec --maintainers ./history/MAINTAINERS_v2.0.md ../../versions/2.0.md > ../../deploy/oas/v2.0.html + +latest=`git describe --abbrev=0 --tags` +for filename in ../../versions/[3456789].*.md ; do + version=$(basename "$filename" .md) + node md2html.js --respec --maintainers ../../MAINTAINERS.md ${filename} > ../../deploy/oas/v$version.html + if [ $version = $latest ]; then + if [[ ${version} != *"rc"* ]];then + # version is not a Release Candidate + cp -p ../../deploy/oas/v$version.html ../../deploy/oas/latest.html + fi + fi +done + diff --git a/scripts/md2html/gist.css b/scripts/md2html/gist.css new file mode 100644 index 0000000000..155f0b9160 --- /dev/null +++ b/scripts/md2html/gist.css @@ -0,0 +1,71 @@ +/** + * GitHub Gist Theme + * Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro + */ + +.hljs { + display: block; + background: white; + padding: 0.5em; + color: #333333; + overflow-x: auto; +} + +.hljs-comment, +.hljs-meta { + color: #969896; +} + +.hljs-string, +.hljs-variable, +.hljs-template-variable, +.hljs-strong, +.hljs-emphasis, +.hljs-quote { + color: #df5000; +} + +.hljs-keyword, +.hljs-selector-tag, +.hljs-type { + color: #a71d5d; +} + +.hljs-literal, +.hljs-symbol, +.hljs-bullet, +.hljs-attribute { + color: #0086b3; +} + +.hljs-section, +.hljs-name { + color: #63a35c; +} + +.hljs-tag { + color: #333333; +} + +.hljs-title, +.hljs-attr, +.hljs-selector-id, +.hljs-selector-class, +.hljs-selector-attr, +.hljs-selector-pseudo { + color: #795da3; +} + +.hljs-addition { + color: #55a532; + background-color: #eaffea; +} + +.hljs-deletion { + color: #bd2c00; + background-color: #ffecec; +} + +.hljs-link { + text-decoration: underline; +} diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js new file mode 100644 index 0000000000..26448d1081 --- /dev/null +++ b/scripts/md2html/md2html.js @@ -0,0 +1,310 @@ +/* bikeshed claims to support markdown syntax, but not (yet) commonmark. +ReSpec supports markdown formatting, but this shows up on the page before being rendered +Hence we render the markdown to HTML ourselves, this gives us +complete control over formatting and syntax highlighting (where +highlight.js does a better job than bikeshed's Pygments) */ + +'use strict'; + +/** +@author Mike Ralphson +**/ + +const fs = require('fs'); +const path = require('path'); +const url = require('url'); +const util = require('util'); + +const hljs = require('highlight.js'); +const cheerio = require('cheerio'); + +let argv = require('yargs') + .boolean('bikeshed') + .alias('b','bikeshed') + .describe('bikeshed','Output in bikeshed format') + .boolean('respec') + .alias('r','respec') + .describe('respec','Output in respec format') + .default('respec',true) + .string('maintainers') + .alias('m','maintainers') + .describe('maintainers','path to MAINTAINERS.md') + .require(1) + .argv; +let maintainers = []; +let emeritus = []; + +const md = require('markdown-it')({ + html: true, + linkify: true, + typographer: true, + highlight: function (str, lang) { + if (lang && hljs.getLanguage(lang)) { // && !argv.respec) { + try { + return '
' +
+                  hljs.highlight(str, { language: lang }).value +
+                  '
'; + } catch (__) { } + } + + return '
' + md.utils.escapeHtml(str) + '
'; + } +}); + +function preface(title,options) { + const respec = { + specStatus: "base", + editors: maintainers, + formerEditors: emeritus, + publishDate: options.publishDate, + subtitle: 'Version '+options.subtitle, + processVersion: 2017, + edDraftURI: "https://github.com/OAI/OpenAPI-Specification/", + github: { + repoURL: "https://github.com/OAI/OpenAPI-Specification/", + branch: "master" + }, + shortName: "OAS", + noTOC: false, + lint: false, + additionalCopyrightHolders: "the Linux Foundation", + includePermalinks: true + }; + + let preface = `${md.utils.escapeHtml(title)}`; + if (options.respec) { + preface += ''; + preface += ``; + preface += fs.readFileSync('./analytics/google.html','utf8'); + preface += ''; + preface += ''; + preface += '
'; + preface += 'The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.'; + preface += '
'; + preface += '
'; + preface += '

Status of This Document

'; + preface += 'The source-of-truth for the specification is the GitHub markdown file referenced above.'; + preface += '
'; + } + else { + preface += ''; + } + return preface; +} + +function doMaintainers() { + let m = fs.readFileSync(argv.maintainers,'utf8'); + let h = md.render(m); + let $ = cheerio.load(h); + let u = $('ul').first(); + $(u).children('li').each(function(e){ + let t = $(this).text().split('@')[0]; + maintainers.push({name:t}); + }); + u = $('ul').eq(1); + $(u).children('li').each(function(e){ + let t = $(this).text().split('@')[0]; + emeritus.push({name:t}); + }); +} + +function getPublishDate(m) { + let h = md.render(m); + let $ = cheerio.load(h); + let t = $('tbody').last(); + let c = $(t).children('tr').children('td'); + let v = $(c[0]).text(); + let d = $(c[1]).text(); + argv.subtitle = v; + if (d === 'TBA') return new Date(); + return new Date(d); +} + +if (argv.maintainers) { + doMaintainers(); +} + +let s = fs.readFileSync(argv._[0],'utf8'); + +if (argv.respec) { + argv.publishDate = getPublishDate(s); +} + +let lines = s.split('\r').join().split('\n'); + +let prevHeading = 0; +let lastIndent = 0; +let inTOC = false; +let inDefs = false; +let inCodeBlock = false; +let bsFix = true; + +let indents = [0]; + +// process the markdown +for (let l in lines) { + let line = lines[l]; + + if (line.startsWith('## Table of Contents')) inTOC = true; + if (line.startsWith('