diff --git a/.github/templates/agenda.md b/.github/templates/agenda.md new file mode 100644 index 0000000000..38c630c9e9 --- /dev/null +++ b/.github/templates/agenda.md @@ -0,0 +1,22 @@ +**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 - [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification/blob/main/CODE_OF_CONDUCT.md#code-of-conduct) + +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** + +![F10B5460-B4B3-4463-9CDE-C7F782202EA9](https://user-images.githubusercontent.com/21603/121568843-0b260900-ca18-11eb-9362-69fda4162be8.jpeg) + +The agenda backlog is currently maintained in issue #2482 + +| Topic | Owner | Decision/NextStep | +|-------|---------|---------| +| | | | +Reports from Special Interest Groups | TDC | | +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..b1f32e4477 --- /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 16 * * 4' + 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 + 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/respec.yaml b/.github/workflows/respec.yaml new file mode 100644 index 0000000000..bc3a9e88d5 --- /dev/null +++ b/.github/workflows/respec.yaml @@ -0,0 +1,57 @@ +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 + with: + fetch-depth: 0 + + - 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/.github/workflows/schema-tests.yaml b/.github/workflows/schema-tests.yaml new file mode 100644 index 0000000000..11a699bf9e --- /dev/null +++ b/.github/workflows/schema-tests.yaml @@ -0,0 +1,31 @@ +name: schema-test + +# Author: @MikeRalphson / runs @jdesrosiers tests +# Issue: https://github.com/OAI/OpenAPI-Specification/pull/2489 + +# +# This workflow runs the npm test script to validate passing and failing +# testcases for the metaschema. +# + +# run this on push to any branch and creation of pull-requests +on: + push: {} + pull_request: {} + workflow_dispatch: {} + +jobs: + test: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v1 # checkout repo content + - uses: actions/setup-node@v1 # setup Node.js + with: + node-version: '14.x' + - name: Install dependencies + run: npm i + - name: Run tests + run: npm run test + diff --git a/.github/workflows/validate-markdown.yaml b/.github/workflows/validate-markdown.yaml index a127677452..7cba565cd5 100644 --- a/.github/workflows/validate-markdown.yaml +++ b/.github/workflows/validate-markdown.yaml @@ -18,10 +18,10 @@ 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' + node-version: '14.x' - name: Validate markdown run: npx mdv versions/3.*.md 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/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 37a9b6e40e..a87b404e6d 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -94,13 +94,50 @@ offender, banning the offender from various online spaces (temporary or permanent), removing the offender from an event with no refund, or other options deemed appropriate. -Further details of specific enforcement policies are currently being -drafted. When these details are completed we will post updates to our -website for transparency. - -Project maintainers who do not report possible incidents or follow -responses in good faith may face temporary or permanent repercussions as -determined by the Code of Conduct Committee. +Enforcement Guidelines +---------------------- + +The Code of Conduct committee will follow these Enforcement Guidelines in +determining the consequences for any action they deem in violation of this +Code of Conduct: + +#### 1. Correction +Community Impact: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +Consequence: A private, written warning from the Code of Conduct committee, +providing clarity around the nature of the violation and an explanation of +why the behavior was inappropriate. A public apology may be requested. + +#### 2. Warning +Community Impact: A violation through a single incident or series of +actions. + +Consequence: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with the Code of Conduct committee, for a specified period of time. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a temporary +or permanent ban. + +#### 3. Temporary Ban +Community Impact: A serious violation of community standards, including +sustained inappropriate behavior. + +Consequence: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with the Code of Conduct committee, is allowed +during this period. Violating these terms may lead to a permanent ban. + +#### 4. Permanent Ban +Community Impact: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of +an individual, or aggression toward or disparagement of classes of +individuals. + +Consequence: A permanent ban from any sort of public interaction +within the community. ### Events diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8a768b3d1c..42347f57af 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -24,7 +24,7 @@ The specification *will evolve over time*. Changes may be made when any of the For each change in the specification we should *always* consider the following: -* Migration. Is this a construct that has a path from the existing 2.0 specification? If so, how complicated is it to migrate to the proposed change? +* Migration. Is this a construct that has a path from the [existing specification](https://github.com/OAI/OpenAPI-Specification/releases))? If so, how complicated is it to migrate to the proposed change? * Tooling. Strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. @@ -36,11 +36,11 @@ Spec changes should be approved by a majority of the committers. Approval can be * GitHub is the medium of record 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 **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 latest document (versions/3.0.0.md for example). * 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/IMPLEMENTATIONS.md b/IMPLEMENTATIONS.md index 868123c6cd..4432288763 100644 --- a/IMPLEMENTATIONS.md +++ b/IMPLEMENTATIONS.md @@ -6,8 +6,9 @@ These tools are not endorsed by the OAI. #### Low-Level tooling -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| +| Title | Project Link | Language | Description | +|-------|--------------|----------|-------------| +| oasdiff | [github/tufin/oasdiff](https://github.com/tufin/oasdiff) | Go | Diff tool for OpenAPI 3.x specs, written as a Golang module | | swagger-parser | [github/swagger-api](https://github.com/swagger-api/swagger-parser) | Java | Swagger 1.0, 1.1, 1.2, 2.0 to OpenAPI Specification converter | | swagger-models | [github/swagger-api](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-models) | Java | OpenAPI 3.0 Java Pojos | | springdoc-openapi | [github/springdoc/springdoc-openapi](https://github.com/springdoc/springdoc-openapi) | Java | Library that produces OpenAPI 3.x specification documentation for spring-boot applications. | @@ -22,15 +23,20 @@ These tools are not endorsed by the OAI. | go-openapi | [github/nasa9084/go-openapi](https://github.com/nasa9084/go-openapi) | Go | Golang struct model for OpenAPI 3.x. | | openapi | [github/wzshiming/openapi](https://github.com/wzshiming/openapi) | Go | OpenAPI 3 Specification for golang | | kin-openapi | [github/getkin/kin-openapi](https://github.com/getkin/kin-openapi) | Go | OpenAPI 3.x implementation for Go (parsing, converting, validation) | +| openapi-go | [github/swaggest/openapi-go](https://github.com/swaggest/openapi-go) | Go | Type-safe OpenAPI 3.x bindings and generator from code | +| openapi | [sv-tools/openapi](https://github.com/sv-tools/openapi) | Go | OpenAPI v3.1 Spec implementation in Go with generics | | Spectral | [github/stoplightio/spectral](https://github.com/stoplightio/spectral) | TypeScript, JavaScript | A flexible JSON object linter with out of the box support for OpenAPI Specification 2 and 3 | | openapi-validator | [gitlab/mmal/openapi-validator](https://gitlab.com/mmalawski/openapi-validator) | PHP | Validates response against OpenAPI schema | | OpenAPI-Delphi | [github/paolo-rossi/OpenAPI-Delphi](https://github.com/paolo-rossi/OpenAPI-Delphi) | Delphi | Delphi implementation of a generator, parser and validator for the OpenAPI 3 Specification | | spring-openapi | [github/jrcodeza/spring-openapi](https://github.com/jrcodeza/spring-openapi) | Java | OpenAPI v3 generator for Java Spring. Includes also client generation. Supports inheritance with discriminators and Jackson annotations and custom interceptors. | +| schema2dts | [nfroidure/schema2dts](https://github.com/nfroidure/schema2dts) | Typescript | Create types definitions from an OpenAPI schema. | +| openapi-runtime-expression | [char0n/openapi-runtime-expression](https://github.com/char0n/openapi-runtime-expression) | JavaScript | OpenAPI Runtime Expressions parser and validator. | #### Editors -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| +| Title | Project Link | Language | Description | +|-------|--------------|----------|-------------| +| Oxygen OpenAPI Editor | [OpenAPI (Swagger) Editor](https://www.oxygenxml.com/openapi.html) | Java | OpenAPI editor with a variety of editing features and helper views. Support for validation and editing OpenAPI 2.0, 3.0, and 3.1 based on JSON Schema specification. Includes a tool for generating documentations and a tool for testing OpenAPIs. | | Visual Studio Code extension | [VS Code marketplace / OpenAPI (Swagger) editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) | TypeScript | Extends VS Code to provide OpenAPI 2.0 and 3.0 navigation, code snippets, new API creation | | Apicurio Studio | [github/Apicurio/apicurio-studio](https://github.com/Apicurio/apicurio-studio) | Java/TypeScript | Web-Based **visual designer** for OpenAPI 2.0 and 3.0.0. | | KaiZen OpenAPI Editor | [github/RepreZen/KaiZen-OpenAPI-Editor](https://github.com/RepreZen/KaiZen-OpenAPI-Editor) | Java | Eclipse Editor for OpenAPI 2.0 and 3.0 | @@ -42,45 +48,61 @@ These tools are not endorsed by the OAI. #### User Interfaces -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| +| Title | Project Link | Language | Description | +|-------|--------------|----------|-------------| | 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 OpenAPI v3 | | WebSphere Liberty | [Download jar](https://developer.ibm.com/wasdev/downloads/) | JavaScript | Includes a native OpenAPI v3 UI which allows for customization of its banners and URL | | Widdershins | [github/Mermade/widdershins](https://github.com/Mermade/widdershins) | Node.js | Generate Slate/Shins markdown from OpenAPI 3.0.x | | angular-swagger-ui | [github/angular-swagger-ui](https://github.com/Orange-OpenSource/angular-swagger-ui) | AngularJS | An angularJS implementation of Swagger UI | -| Redoc | [github/Redocly/redoc](https://github.com/Redocly/redoc) | JavaScript | A React-based renderer with deep support for OAS v2 and v3 and zero dev-dependency| +| Redoc | [github/Redocly/redoc](https://github.com/Redocly/redoc) | JavaScript | A React-based renderer with deep support for OAS v2 and v3 and zero dev-dependency | +| RapiDoc | [github/mrin9/RapiDoc](https://github.com/mrin9/RapiDoc) | JavaScript | A highly customizable Web Component for viewing Swagger and OpenAPI definitions | +| Bump.sh | [github/bump-sh/CLI](https://github.com/bump-sh/cli) | NodeJS | Generate documentations from OpenAPI contracts, visualize changelogs and get notified of breaking changes | #### Mock Servers -| Title | Project Link | Language | Description | -| -------------- | ------------ | -------- | ----------- | + +| Title | Project Link | Language | Description | +|-------|--------------|----------|-------------| | API Sprout | [github/danielgtaylor/apisprout](https://github.com/danielgtaylor/apisprout) | Go | Lightweight, blazing fast, cross-platform OpenAPI 3 mock server with validation | +#### Testing tools +| Title | Project Link | Language | Description | +| ------|--------------|----------|-------------| +| Schemathesis | [github/schemathesis/schemathesis](https://github.com/schemathesis/schemathesis) | Python | A modern API testing tool for web applications built with OpenAPI and GraphQL specifications | +| Tcases for OpenAPI | [github/Cornutum/tcases](https://github.com/Cornutum/tcases/blob/master/tcases-openapi/README.md#tcases-for-openapi-from-rest-ful-to-test-ful) | Java | Generates test cases directly from an OpenAPI 3.0.X definition. Creates tests executable using various test frameworks. Bonus: Semantic linter reports elements that are inconsistent, superfluous, or dubious. | + #### Server Implementations -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| + +| Title | Project Link | Language | Description | +|-------|--------------|----------|-------------| | Vert.x Web API Contract | [github/vert-x3/vertx-web](http://vertx.io/docs/#web) | Java, Kotlin, JavaScript, Groovy, Ruby, Ceylon & Scala | Create an API endpoint with Vert.x 3 and OpenAPI 3 with automatic requests validation | Fusio | [github/apioo/fusio](https://github.com/apioo/fusio) | PHP, JavaScript | Build API endpoints based on OpenAPI 3 | Modern | [github/modern-project/modern-ruby](https://github.com/modern-project/modern-ruby) | Ruby | OpenAPI 3-based Rack framework with automatic OAS generation and requests/response validation -| Koa2-OAS3 | [github/OverSpeedIO/koa2-oas3](https://github.com/OverSpeedIO/koa2-oas3) | Node.js | OpenAPI 3 request validation middleware for Koa2 based apps. | Exegesis | [github/exegesis-js/exegesis](https://github.com/exegesis-js/exegesis) | Node.js | OpenAPI 3 server-side framework for express and other frameworks. | PHP-CRUD-API | [github/mevdschee/php-crud-api](https://github.com/mevdschee/php-crud-api) | PHP | Automatic CRUD API with OpenAPI 3 docs | FastAPI | [github/tiangolo/fastapi](https://github.com/tiangolo/fastapi) | Python | OpenAPI 3 based, high performance, Python 3.6+ API framework with automatic data validation, serialization and great editor support. | Fastify OpenAPI v3 | [gitlab.com/m03geek/fastify-oas](https://gitlab.com/m03geek/fastify-oas) | Node.JS | Fastify OpenAPI v3+ plugin. Generates OpenAPI specification from fastify schemas and routes. Also serves swagger ui and spec in json/yaml formats. | openapi-backend | [github/anttiviljami/openapi-backend](https://github.com/anttiviljami/openapi-backend) | Node.js, TypeScript | Build, Validate, Route, and Mock in the backend using OpenAPI v3 spec in your favourite framework +| Connexion | [github/zalando/connexion](https://github.com/zalando/connexion) | Python | Swagger/OpenAPI First framework for Python on top of Flask with automatic endpoint validation & OAuth2 support +| JSONSchema::Validator | [https://github.com/skbkontur/perl-jsonschema-validator](https://github.com/skbkontur/perl-jsonschema-validator) | Perl | OpenAPI 3 request/response validation +| rest | [github.com/swaggest/rest](https://github.com/swaggest/rest) | Go | API server with automatic request/response mapping/validation and OpenAPI schema +| whook | [nfroidure/whook](https://github.com/nfroidure/whook) | Typescript | OpenAPI 3 based NodeJS server. | #### Client Implementations -| Title | Project Link | Language | Description | -|----------------|--------------|----------|-------------| +| Title | Project Link | Language | Description | +|-------|--------------|----------|-------------| | Scorpio | [github/notEthan/scorpio](https://github.com/notEthan/Scorpio) | Ruby | OpenAPI 2 and 3 implementation offering a HTTP client library | | openapi-client-axios | [github/anttiviljami/openapi-client-axios](https://github.com/anttiviljami/openapi-client-axios) | JavaScript, TypeScript | JavaScript client library for consuming OpenAPI-enabled APIs with axios. Types included. +| restful-react | [github/contiamo/restful-react](https://github.com/contiamo/restful-react) | Typescript | Well tested library to generate typesafe hooks and components. Easy to integrate into your development process. | +| openapi-ts-sdk-builder | [nfroidure/openapi-ts-sdk-builder](https://github.com/nfroidure/openapi-ts-sdk-builder) | Typescript | Generate a TypeScript SDK from OpenAPI 3 definitions. | +| aiopenapi3 | [github.com/commonism/aiopenapi3](https://github.com/commonism/aiopenapi3) | Python | OpenAPI 3, Python3.7+ client & validator with automatic data validation & serialization, sync or asyncio. #### Code Generators -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| +| Title | Project Link | Language | Description | +|-------|--------------|----------|-------------| | 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. | | Gen | [github/wzshiming/gen](https://github.com/wzshiming/gen) | Go | Generate OpenAPI 3, client, and route based on golang source code. | @@ -91,3 +113,4 @@ These tools are not endorsed by the OAI. | swagger-node-codegen | [github/fmvilas/swagger-node-codegen](https://github.com/fmvilas/swagger-node-codegen) | Node.js | Generates a Node.js/express server, but also has a template engine for creating any templates needed. | .NET-C#-Annotations | [github/Microsoft/OpenAPI-NET-CSharpAnnotations](https://github.com/Microsoft/OpenAPI.NET.CSharpAnnotations) | dotnet | Convert your native C# comments/annotation XML from your API code into a OpenAPI document object. | | Object Oriented OpenAPI Specification | [github/goldspecdigital/oooas](https://github.com/goldspecdigital/oooas) | PHP | Generates OpenAPI documents using PHP. | +| swac | [github.com/swaggest/swac](https://github.com/swaggest/swac) | PHP, Go | Generates clients for Go and PHP from OpenAPI 2/3. | diff --git a/README.md b/README.md index 0a81ca7f21..dcdc895a1b 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,17 @@ # The OpenAPI Specification -![Build Status](https://github.com/OAI/OpenAPI-Specification/workflows/validate-markdown/badge.svg) +![Build Status](https://github.com/OAI/OpenAPI-Specification/workflows/validate-markdown/badge.svg) [![Issue triagers](https://www.codetriage.com/oai/openapi-specification/badges/users.svg)](https://www.codetriage.com/oai/openapi-specification) ![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) The OpenAPI Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. -The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP 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. +The OpenAPI Specification (OAS) defines a standard and programming language-agnostic interface description for HTTP 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 minimal implementation logic. Similar to what interface descriptions do for lower-level programming, the OpenAPI Specification removes the guesswork in calling a service. -Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe an APIs services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application. +Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe APIs services and are represented in YAML or JSON formats. These documents may be produced and served statically or generated dynamically from an application. -The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service – the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI – this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a HTTP API. +The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service – the described service may not even be owned by the creator of its description. It does, however, require the service's capabilities be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI – this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with an HTTP API. This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project. @@ -36,23 +36,24 @@ Looking to see how you can create your own OpenAPI definition, present it, or ot ## Participation -The current process for development of the OpenAPI Specification is described in +The current process for developing 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. +Developing 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). +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 entire OpenAPI [technical meeting calendar](https://calendar.google.com/calendar/u/0/embed?src=c_fue82vsncog6ahhjvuokjo8qsk@group.calendar.google.com) online. The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions: * Review the [current specification](versions/3.1.0.md). The human-readable markdown file _is the source of truth_ for the specification. * Review the [development](DEVELOPMENT.md) process so you understand how the spec is evolving. * Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR. +* Subscribe to an open issue a day (or a week) in your inbox via [CodeTriage.com](https://www.codetriage.com/oai/openapi-specification). * Create an issue to describe a new concern. If possible, propose a solution. -Not all feedback can be accommodated and there may be solid arguments for or against a change being appropriate for the specification. +Not all feedback can be accommodated, and there may be solid arguments for or against a change being appropriate for the specification. ## 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/SPECIAL_INTEREST_GROUPS.md b/SPECIAL_INTEREST_GROUPS.md new file mode 100644 index 0000000000..8b13789179 --- /dev/null +++ b/SPECIAL_INTEREST_GROUPS.md @@ -0,0 +1 @@ + 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 diff --git a/examples/v3.0/petstore.json b/examples/v3.0/petstore.json index 583b1e0990..8571c0b0b0 100644 --- a/examples/v3.0/petstore.json +++ b/examples/v3.0/petstore.json @@ -28,6 +28,7 @@ "required": false, "schema": { "type": "integer", + "maximum": 100, "format": "int32" } } @@ -152,6 +153,7 @@ }, "Pets": { "type": "array", + "maxItems": 100, "items": { "$ref": "#/components/schemas/Pet" } diff --git a/examples/v3.0/petstore.yaml b/examples/v3.0/petstore.yaml index 534bb0cd77..fa14a9781d 100644 --- a/examples/v3.0/petstore.yaml +++ b/examples/v3.0/petstore.yaml @@ -20,6 +20,7 @@ paths: required: false schema: type: integer + maximum: 100 format: int32 responses: '200': @@ -96,6 +97,7 @@ components: type: string Pets: type: array + maxItems: 100 items: $ref: "#/components/schemas/Pet" Error: diff --git a/examples/v3.1/non-oauth-scopes.json b/examples/v3.1/non-oauth-scopes.json new file mode 100644 index 0000000000..b3e5990426 --- /dev/null +++ b/examples/v3.1/non-oauth-scopes.json @@ -0,0 +1,31 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Non-oAuth Scopes example", + "version": "1.0.0" + }, + "paths": { + "/users": { + "get": { + "security": [ + { + "bearerAuth": [ + "read:users", + "public" + ] + } + ] + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "jwt", + "description": "note: non-oauth scopes are not defined at the securityScheme level" + } + } + } +} \ No newline at end of file diff --git a/examples/v3.1/non-oauth-scopes.yaml b/examples/v3.1/non-oauth-scopes.yaml new file mode 100644 index 0000000000..e757452f38 --- /dev/null +++ b/examples/v3.1/non-oauth-scopes.yaml @@ -0,0 +1,19 @@ +openapi: 3.1.0 +info: + title: Non-oAuth Scopes example + version: 1.0.0 +paths: + /users: + get: + security: + - bearerAuth: + - 'read:users' + - 'public' +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: jwt + description: 'note: non-oauth scopes are not defined at the securityScheme level' + 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/package.json b/package.json index 59851cb7dc..08cbfdd010 100644 --- a/package.json +++ b/package.json @@ -12,12 +12,20 @@ "url": "https://github.com/OAI/OpenAPI-Specification.git" }, "license": "Apache-2.0", + "scripts": { + "test": "npx mocha tests/**/test.js" + }, "readmeFilename": "README.md", "files": [ "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/proposals/000_OAS-proposal-template.md b/proposals/2019-01-01-Proposal-Template.md similarity index 89% rename from proposals/000_OAS-proposal-template.md rename to proposals/2019-01-01-Proposal-Template.md index da2a8b1eeb..aae45e00a5 100644 --- a/proposals/000_OAS-proposal-template.md +++ b/proposals/2019-01-01-Proposal-Template.md @@ -5,12 +5,12 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})| +|Proposal |[YYYY-MM-DD-Short-Name](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{YYYY-MM-DD-Short-Name.md})| |Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})| -|Review Manager |TBD | +|Review Manager | TBD | |Status |Proposal, Draft, Promoted, or Abandoned| -|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)| -|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})| +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{YYYY-MM-DD-Short-Name}/implementations.md)| +|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{IssueId})| |Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | ## Change Log diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/2019-03-15-Alternative-Schema.md similarity index 75% rename from proposals/001_Alternative Schema Proposal.md rename to proposals/2019-03-15-Alternative-Schema.md index 9f176ea28e..de53463736 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/2019-03-15-Alternative-Schema.md @@ -4,11 +4,11 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| -|Authors|[Chuck Heazel](https://github.com/{cmheazel})| +|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/2019-03-15-Alternative-Schema.md)| +|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-Schema/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) | @@ -16,8 +16,8 @@ |Date |Responsible Party |Description | |---- | ---------------- | ---------- | -|3/15/19 |C. Heazel|Initial Markup Draft | -|4/17/19 |C. Heazel|Re-structured based on Apple Swift| +|2019-03-15 |C. Heazel|Initial Markup Draft | +|2019-04-17 |C. Heazel|Re-structured based on Apple Swift| ## Introduction @@ -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 @@ -57,7 +57,7 @@ Values used to populate the Alternative Schema Object are required to come from *** Note this is a placeholder registry. Don't take the values seriously. *** -Inital contents of the registry will include: +Initial contents of the registry will include: |Name |Link |Description | |--- | --- | --- | @@ -69,5 +69,5 @@ This proposal makes use of the extensibility features of OpenAPI. All changes so ## Alternatives considered -Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an extenal link was prefered. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language. +Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an external link was preferred. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language. diff --git a/proposals/002_Webhooks.md b/proposals/2019-07-17-Webhooks.md similarity index 95% rename from proposals/002_Webhooks.md rename to proposals/2019-07-17-Webhooks.md index 8ad8a97fa9..493b444451 100644 --- a/proposals/002_Webhooks.md +++ b/proposals/2019-07-17-Webhooks.md @@ -5,7 +5,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/002_webhooks.md)| +|Proposal |[2019-07-17-Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/2019-07-17-Webhooks.md)| |Authors|[Lorna Mitchell](https://github.com/lornajane)| |Review Manager |TBD | |Status |Proposal| @@ -19,7 +19,7 @@ ## Introduction -Modern APIs often consist of two-way API traffic, but OpenAPI currently only supports some types of requests. Standard client-to-server API calls are well supported. Server-to-client callbacks are only supported if they are the result of an earlier API call and are documented by nesting under the path of that earlier call. Incoming HTTP reqests ("webhooks") cannot be described in the current version of OpenAPI if they are the result of subscription arranged outside of the scope of the API (e.g. by setting a callback URL in a web interface). +Modern APIs often consist of two-way API traffic, but OpenAPI currently only supports some types of requests. Standard client-to-server API calls are well supported. Server-to-client callbacks are only supported if they are the result of an earlier API call and are documented by nesting under the path of that earlier call. Incoming HTTP requests ("webhooks") cannot be described in the current version of OpenAPI if they are the result of subscription arranged outside of the scope of the API (e.g. by setting a callback URL in a web interface). ## Motivation @@ -189,4 +189,4 @@ Adding a new top-level entry is not something to take lightly, however hopefully ## Alternatives considered -Another option is to add a special `path` that could contain the various webhooks using the exisiting `callback` syntax but existing tools which aren't expecting this special value may not handle it well, so this option was discounted. +Another option is to add a special `path` that could contain the various webhooks using the existing `callback` syntax but existing tools which aren't expecting this special value may not handle it well, so this option was discounted. diff --git a/proposals/003_Clarify-Nullable.md b/proposals/2019-10-31-Clarify-Nullable.md similarity index 98% rename from proposals/003_Clarify-Nullable.md rename to proposals/2019-10-31-Clarify-Nullable.md index 139b0dceef..9d437c150c 100644 --- a/proposals/003_Clarify-Nullable.md +++ b/proposals/2019-10-31-Clarify-Nullable.md @@ -5,10 +5,10 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[003](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/003_Clarify-Nullable.md)| +|Proposal |[2019-10-31-Clarify-Nullable](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/2019-10-31-Clarify-Nullable.md)| |Authors|[Ted Epstein](https://github.com/tedepstein)| |Review Manager |TBD| -|Status |Proposal| +|Status |Promoted| |Implementations |N/A| |Issues | [1900](https://github.com/OAI/OpenAPI-Specification/issues/1900), [1368](https://github.com/OAI/OpenAPI-Specification/issues/1368), [1389](https://github.com/OAI/OpenAPI-Specification/issues/1389), [1957](https://github.com/OAI/OpenAPI-Specification/pull/1957), [2046](https://github.com/OAI/OpenAPI-Specification/pull/2046), [1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957), [2057](https://github.com/OAI/OpenAPI-Specification/issues/2057)| |Previous Revisions |N/A | @@ -18,6 +18,7 @@ |Date |Responsible Party |Description | |---- | ---------------- |------------| |Oct 31, 2019 | Ted Epstein | Initial proposal | +|Apr 8, 2021 | Ted Epstein | Update status to Promoted. The proposal was adopted in [OpenAPI 3.0.3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md). | ## Introduction diff --git a/proposals/004_Overlays.md b/proposals/2019-12-24-Overlays.md similarity index 98% rename from proposals/004_Overlays.md rename to proposals/2019-12-24-Overlays.md index de820558ba..7b9bc0cadf 100644 --- a/proposals/004_Overlays.md +++ b/proposals/2019-12-24-Overlays.md @@ -4,7 +4,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/004_overlays.md)| +|Proposal |[2019-12-24-Overlays](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/2019-12-24-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)| @@ -52,7 +52,7 @@ This object contains identifying information about the [OpenAPI Overlay document Field Name | Type | Description ---|:---:|--- title | `string` | A human readable description of the purpose of the overlay. -version | `string` | A version identifer for indicating changes to an overlay document. +version | `string` | A version identifier for indicating changes to an overlay document. #### Update Object diff --git a/proposals/Alternative Schema/DEVELOPMENT.md b/proposals/Alternative Schema/DEVELOPMENT.md deleted file mode 100644 index 65ff4b1684..0000000000 --- a/proposals/Alternative Schema/DEVELOPMENT.md +++ /dev/null @@ -1,38 +0,0 @@ -## Development Guidelines - -TBD - -## Specification Driving factors - -TBD - -## Specification Change Criteria - -TBD - -## Specification Change Process - -TBD - -## Tracking Process - -* GitHub is the medium of record for all spec designs, use cases, and so on. - - -## Release Process - -TBD - -## Draft Features - - -## Transparency - - - -## Participation - - - -## Community Roles - diff --git a/proposals/Alternative Schema/CONTRIBUTORS.md b/proposals/Alternative-Schema/CONTRIBUTORS.md similarity index 100% rename from proposals/Alternative Schema/CONTRIBUTORS.md rename to proposals/Alternative-Schema/CONTRIBUTORS.md diff --git a/proposals/Alternative Schema/alternative_schema_object.adoc b/proposals/Alternative-Schema/alternative_schema_object.md similarity index 98% rename from proposals/Alternative Schema/alternative_schema_object.adoc rename to proposals/Alternative-Schema/alternative_schema_object.md index 011f26b6b6..a59451bce3 100644 --- a/proposals/Alternative Schema/alternative_schema_object.adoc +++ b/proposals/Alternative-Schema/alternative_schema_object.md @@ -6,7 +6,7 @@ The following text is to be inserted after the XML Object section This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification. If tooling does not support the _type_, tooling MUST consider the content valid but SHOULD provide a warning that the alternative schema was not processed. -==== Fixed Fields +## Fixed Fields |Field Name | Type | Description | |---|:---:|---| @@ -14,3 +14,4 @@ This object makes it possible to reference an external file that contains a sche |location | url | **REQUIRED**. This is a absolute or relative reference to an external resource containing a schema of a known type. This reference may contain a fragment identifier to reference only a subset of an external document. | This object MAY be extended with Specification Extensions. + diff --git a/proposals/Alternative Schema/alternative_schema_examples.md b/proposals/Alternative-Schema/examples.md similarity index 100% rename from proposals/Alternative Schema/alternative_schema_examples.md rename to proposals/Alternative-Schema/examples.md diff --git a/proposals/Alternative Schema/implementations.md b/proposals/Alternative-Schema/implementations.md similarity index 100% rename from proposals/Alternative Schema/implementations.md rename to proposals/Alternative-Schema/implementations.md diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative-Schema/schema_object.md similarity index 73% rename from proposals/Alternative Schema/schema_object.md rename to 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. | diff --git a/schemas/v1.2/operationObject.json b/schemas/v1.2/operationObject.json index 371a6cc82c..5661251eb7 100644 --- a/schemas/v1.2/operationObject.json +++ b/schemas/v1.2/operationObject.json @@ -8,7 +8,7 @@ "required": [ "method", "nickname", "parameters" ], "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS" ] }, - "summary": { "type": "string", "maxLength": 120 }, + "summary": { "type": "string" }, "notes": { "type": "string" }, "nickname": { "type": "string", diff --git a/schemas/v3.0/schema.json b/schemas/v3.0/schema.json index 71808402f6..4360553fe5 100644 --- a/schemas/v3.0/schema.json +++ b/schemas/v3.0/schema.json @@ -1,7 +1,7 @@ { - "id": "https://spec.openapis.org/oas/3.0/schema/2019-04-02", + "id": "https://spec.openapis.org/oas/3.0/schema/2021-09-28", "$schema": "http://json-schema.org/draft-04/schema#", - "description": "Validation schema for OpenAPI Specification 3.0.X.", + "description": "The description of OpenAPI v3.0.x documents, as defined by https://spec.openapis.org/oas/v3.0.3", "type": "object", "required": [ "openapi", @@ -1358,9 +1358,8 @@ "description": "Bearer", "properties": { "scheme": { - "enum": [ - "bearer" - ] + "type": "string", + "pattern": "^[Bb][Ee][Aa][Rr][Ee][Rr]$" } } }, @@ -1374,9 +1373,8 @@ "properties": { "scheme": { "not": { - "enum": [ - "bearer" - ] + "type": "string", + "pattern": "^[Bb][Ee][Aa][Rr][Ee][Rr]$" } } } @@ -1489,7 +1487,8 @@ "PasswordOAuthFlow": { "type": "object", "required": [ - "tokenUrl" + "tokenUrl", + "scopes" ], "properties": { "tokenUrl": { @@ -1516,7 +1515,8 @@ "ClientCredentialsFlow": { "type": "object", "required": [ - "tokenUrl" + "tokenUrl", + "scopes" ], "properties": { "tokenUrl": { @@ -1544,7 +1544,8 @@ "type": "object", "required": [ "authorizationUrl", - "tokenUrl" + "tokenUrl", + "scopes" ], "properties": { "authorizationUrl": { @@ -1628,7 +1629,14 @@ "headers": { "type": "object", "additionalProperties": { - "$ref": "#/definitions/Header" + "oneOf": [ + { + "$ref": "#/definitions/Header" + }, + { + "$ref": "#/definitions/Reference" + } + ] } }, "style": { @@ -1651,4 +1659,4 @@ "additionalProperties": false } } -} \ No newline at end of file +} diff --git a/schemas/v3.0/schema.yaml b/schemas/v3.0/schema.yaml index 13e47ff08d..e9d70c8e01 100644 --- a/schemas/v3.0/schema.yaml +++ b/schemas/v3.0/schema.yaml @@ -1,6 +1,6 @@ -id: https://spec.openapis.org/oas/3.0/schema/2019-04-02 +id: https://spec.openapis.org/oas/3.0/schema/2021-09-28 $schema: http://json-schema.org/draft-04/schema# -description: Validation schema for OpenAPI Specification 3.0.X. +description: The description of OpenAPI v3.0.x documents, as defined by https://spec.openapis.org/oas/v3.0.3 type: object required: - openapi @@ -495,6 +495,22 @@ definitions: type: string description: type: string + get: + $ref: '#/definitions/Operation' + put: + $ref: '#/definitions/Operation' + post: + $ref: '#/definitions/Operation' + delete: + $ref: '#/definitions/Operation' + options: + $ref: '#/definitions/Operation' + head: + $ref: '#/definitions/Operation' + patch: + $ref: '#/definitions/Operation' + trace: + $ref: '#/definitions/Operation' servers: type: array items: @@ -507,8 +523,6 @@ definitions: - $ref: '#/definitions/Reference' uniqueItems: true patternProperties: - '^(get|put|post|delete|options|head|patch|trace)$': - $ref: '#/definitions/Operation' '^x-': {} additionalProperties: false @@ -806,7 +820,8 @@ definitions: - description: Bearer properties: scheme: - enum: [bearer] + type: string + pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$ - description: Non Bearer not: @@ -814,7 +829,8 @@ definitions: properties: scheme: not: - enum: [bearer] + type: string + pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$ OAuth2SecurityScheme: type: object @@ -892,6 +908,7 @@ definitions: type: object required: - tokenUrl + - scopes properties: tokenUrl: type: string @@ -911,6 +928,7 @@ definitions: type: object required: - tokenUrl + - scopes properties: tokenUrl: type: string @@ -931,6 +949,7 @@ definitions: required: - authorizationUrl - tokenUrl + - scopes properties: authorizationUrl: type: string @@ -987,7 +1006,9 @@ definitions: headers: type: object additionalProperties: - $ref: '#/definitions/Header' + oneOf: + - $ref: '#/definitions/Header' + - $ref: '#/definitions/Reference' style: type: string enum: diff --git a/schemas/v3.1/dialect/base.schema.json b/schemas/v3.1/dialect/base.schema.json index d54b0d4d7c..eae8386e8a 100644 --- a/schemas/v3.1/dialect/base.schema.json +++ b/schemas/v3.1/dialect/base.schema.json @@ -1,6 +1,10 @@ { "$id": "https://spec.openapis.org/oas/3.1/dialect/base", "$schema": "https://json-schema.org/draft/2020-12/schema", + + "title": "OpenAPI 3.1 Schema Object Dialect", + "description": "A JSON Schema dialect describing schemas found in OpenAPI documents", + "$vocabulary": { "https://json-schema.org/draft/2020-12/vocab/core": true, "https://json-schema.org/draft/2020-12/vocab/applicator": true, @@ -11,9 +15,9 @@ "https://json-schema.org/draft/2020-12/vocab/content": true, "https://spec.openapis.org/oas/3.1/vocab/base": false }, + "$dynamicAnchor": "meta", - "title": "OpenAPI 3.1 Schema Object Dialect", "allOf": [ { "$ref": "https://json-schema.org/draft/2020-12/schema" }, { "$ref": "https://spec.openapis.org/oas/3.1/meta/base" } diff --git a/schemas/v3.1/dialect/base.schema.yaml b/schemas/v3.1/dialect/base.schema.yaml new file mode 100644 index 0000000000..30996abb0e --- /dev/null +++ b/schemas/v3.1/dialect/base.schema.yaml @@ -0,0 +1,21 @@ +$id: https://spec.openapis.org/oas/3.1/dialect/base +$schema: https://json-schema.org/draft/2020-12/schema + +title: OpenAPI 3.1 Schema Object Dialect +description: A JSON Schema dialect describing schemas found in OpenAPI documents + +$dynamicAnchor: meta + +$vocabulary: + https://json-schema.org/draft/2020-12/vocab/applicator: true + https://json-schema.org/draft/2020-12/vocab/content: true + https://json-schema.org/draft/2020-12/vocab/core: true + https://json-schema.org/draft/2020-12/vocab/format-annotation: true + https://json-schema.org/draft/2020-12/vocab/meta-data: true + https://json-schema.org/draft/2020-12/vocab/unevaluated: true + https://json-schema.org/draft/2020-12/vocab/validation: true + https://spec.openapis.org/oas/3.1/vocab/base: false + +allOf: + - $ref: https://json-schema.org/draft/2020-12/schema + - $ref: https://spec.openapis.org/oas/3.1/meta/base diff --git a/schemas/v3.1/meta/base.schema.json b/schemas/v3.1/meta/base.schema.json index f3ee03fb96..a7a59f1c7d 100644 --- a/schemas/v3.1/meta/base.schema.json +++ b/schemas/v3.1/meta/base.schema.json @@ -1,11 +1,15 @@ { "$id": "https://spec.openapis.org/oas/3.1/meta/base", "$schema": "https://json-schema.org/draft/2020-12/schema", + + "title": "OAS Base vocabulary", + "description": "A JSON Schema Vocabulary used in the OpenAPI Schema Dialect", + "$vocabulary": { "https://spec.openapis.org/oas/3.1/vocab/base": true }, + "$dynamicAnchor": "meta", - "title": "OAS Base vocabulary", "type": ["object", "boolean"], "properties": { @@ -14,12 +18,14 @@ "externalDocs": { "$ref": "#/$defs/external-docs" }, "xml": { "$ref": "#/$defs/xml" } }, + "$defs": { "extensible": { "patternProperties": { "^x-": true } }, + "discriminator": { "$ref": "#/$defs/extensible", "type": "object", @@ -37,6 +43,7 @@ "required": ["propertyName"], "unevaluatedProperties": false }, + "external-docs": { "$ref": "#/$defs/extensible", "type": "object", @@ -52,6 +59,7 @@ "required": ["url"], "unevaluatedProperties": false }, + "xml": { "$ref": "#/$defs/extensible", "type": "object", diff --git a/schemas/v3.1/meta/base.schema.yaml b/schemas/v3.1/meta/base.schema.yaml new file mode 100644 index 0000000000..e2849e4115 --- /dev/null +++ b/schemas/v3.1/meta/base.schema.yaml @@ -0,0 +1,70 @@ +$id: https://spec.openapis.org/oas/3.1/meta/base +$schema: https://json-schema.org/draft/2020-12/schema + +title: OAS Base vocabulary +description: A JSON Schema Vocabulary used in the OpenAPI Schema Dialect + +$dynamicAnchor: meta + +$vocabulary: + https://spec.openapis.org/oas/3.1/vocab/base: true + +type: + - object + - boolean +properties: + discriminator: + $ref: '#/$defs/discriminator' + example: true + externalDocs: + $ref: '#/$defs/external-docs' + xml: + $ref: '#/$defs/xml' + +$defs: + discriminator: + $ref: '#/$defs/extensible' + properties: + mapping: + additionalProperties: + type: string + type: object + propertyName: + type: string + required: + - propertyName + type: object + unevaluatedProperties: false + + extensible: + patternProperties: + ^x-: true + external-docs: + $ref: '#/$defs/extensible' + properties: + description: + type: string + url: + format: uri-reference + type: string + required: + - url + type: object + unevaluatedProperties: false + + xml: + $ref: '#/$defs/extensible' + properties: + attribute: + type: boolean + name: + type: string + namespace: + format: uri + type: string + prefix: + type: string + wrapped: + type: boolean + type: object + unevaluatedProperties: false diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json index 078af184fe..752e98be4e 100644 --- a/schemas/v3.1/schema-base.json +++ b/schemas/v3.1/schema-base.json @@ -1,23 +1,22 @@ { - "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-03-02", + "$id": "https://spec.openapis.org/oas/3.1/schema-base/2022-10-07", "$schema": "https://json-schema.org/draft/2020-12/schema", - "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + + "description": "The description of OpenAPI v3.1.x documents using the OpenAPI JSON Schema dialect, as defined by https://spec.openapis.org/oas/v3.1.0", + + "$ref": "https://spec.openapis.org/oas/3.1/schema/2022-10-07", "properties": { - "jsonSchemaDialect": { - "$ref": "#/$defs/dialect" - } + "jsonSchemaDialect": { "$ref": "#/$defs/dialect" } }, + "$defs": { - "dialect": { - "const": "https://spec.openapis.org/oas/3.1/dialect/base" - }, + "dialect": { "const": "https://spec.openapis.org/oas/3.1/dialect/base" }, + "schema": { "$dynamicAnchor": "meta", - "$ref\"": "https://spec.openapis.org/oas/3.1/dialect/base", + "$ref": "https://spec.openapis.org/oas/3.1/dialect/base", "properties": { - "$schema": { - "$ref": "#/$defs/dialect" - } + "$schema": { "$ref": "#/$defs/dialect" } } } } diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml index 41a27be7a9..01a5209a01 100644 --- a/schemas/v3.1/schema-base.yaml +++ b/schemas/v3.1/schema-base.yaml @@ -1,7 +1,9 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-03-02' +$id: 'https://spec.openapis.org/oas/3.1/schema-base/2022-10-07' $schema: 'https://json-schema.org/draft/2020-12/schema' -$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +description: The description of OpenAPI v3.1.x documents using the OpenAPI JSON Schema dialect, as defined by https://spec.openapis.org/oas/v3.1.0 + +$ref: 'https://spec.openapis.org/oas/3.1/schema/2022-10-07' properties: jsonSchemaDialect: $ref: '#/$defs/dialect' @@ -9,9 +11,10 @@ properties: $defs: dialect: const: 'https://spec.openapis.org/oas/3.1/dialect/base' + schema: $dynamicAnchor: meta - $ref": 'https://spec.openapis.org/oas/3.1/dialect/base' + $ref: 'https://spec.openapis.org/oas/3.1/dialect/base' properties: $schema: $ref: '#/$defs/dialect' diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index fa987c12d6..468bc7e5f5 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -1,6 +1,7 @@ { - "$id": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + "$id": "https://spec.openapis.org/oas/3.1/schema/2022-10-07", "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "The description of OpenAPI v3.1.x documents without schema validation, as defined by https://spec.openapis.org/oas/v3.1.0", "type": "object", "properties": { "openapi": { @@ -11,11 +12,20 @@ "$ref": "#/$defs/info" }, "jsonSchemaDialect": { - "$ref": "#/$defs/uri", + "type": "string", + "format": "uri", "default": "https://spec.openapis.org/oas/3.1/dialect/base" }, "servers": { - "$ref": "#/$defs/server" + "type": "array", + "items": { + "$ref": "#/$defs/server" + }, + "default": [ + { + "url": "/" + } + ] }, "paths": { "$ref": "#/$defs/paths" @@ -70,6 +80,7 @@ "unevaluatedProperties": false, "$defs": { "info": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#info-object", "type": "object", "properties": { "title": { @@ -82,7 +93,8 @@ "type": "string" }, "termsOfService": { - "type": "string" + "type": "string", + "format": "uri" }, "contact": { "$ref": "#/$defs/contact" @@ -102,22 +114,26 @@ "unevaluatedProperties": false }, "contact": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#contact-object", "type": "object", "properties": { "name": { "type": "string" }, "url": { - "type": "string" + "type": "string", + "format": "uri" }, "email": { - "type": "string" + "type": "string", + "format": "email" } }, "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "license": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#license-object", "type": "object", "properties": { "name": { @@ -127,32 +143,32 @@ "type": "string" }, "url": { - "$ref": "#/$defs/uri" + "type": "string", + "format": "uri" } }, "required": [ "name" ], - "oneOf": [ - { - "required": [ - "identifier" - ] - }, - { - "required": [ - "url" - ] + "dependentSchemas": { + "identifier": { + "not": { + "required": [ + "url" + ] + } } - ], + }, "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "server": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#server-object", "type": "object", "properties": { "url": { - "$ref": "#/$defs/uri" + "type": "string", + "format": "uri-reference" }, "description": { "type": "string" @@ -171,6 +187,7 @@ "unevaluatedProperties": false }, "server-variable": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#server-variable-object", "type": "object", "properties": { "enum": { @@ -183,7 +200,7 @@ "default": { "type": "string" }, - "descriptions": { + "description": { "type": "string" } }, @@ -194,6 +211,7 @@ "unevaluatedProperties": false }, "components": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#components-object", "type": "object", "properties": { "schemas": { @@ -269,6 +287,7 @@ "unevaluatedProperties": false }, "paths": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#paths-object", "type": "object", "patternProperties": { "^/": { @@ -279,6 +298,7 @@ "unevaluatedProperties": false }, "path-item": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#path-item-object", "type": "object", "properties": { "summary": { @@ -298,10 +318,29 @@ "items": { "$ref": "#/$defs/parameter-or-reference" } - } - }, - "patternProperties": { - "^(get|post|delete|options|head|patch|trace)$": { + }, + "get": { + "$ref": "#/$defs/operation" + }, + "put": { + "$ref": "#/$defs/operation" + }, + "post": { + "$ref": "#/$defs/operation" + }, + "delete": { + "$ref": "#/$defs/operation" + }, + "options": { + "$ref": "#/$defs/operation" + }, + "head": { + "$ref": "#/$defs/operation" + }, + "patch": { + "$ref": "#/$defs/operation" + }, + "trace": { "$ref": "#/$defs/operation" } }, @@ -310,6 +349,7 @@ }, "path-item-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -322,6 +362,7 @@ } }, "operation": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#operation-object", "type": "object", "properties": { "tags": { @@ -381,13 +422,15 @@ "unevaluatedProperties": false }, "external-documentation": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#external-documentation-object", "type": "object", "properties": { "description": { "type": "string" }, "url": { - "$ref": "#/$defs/uri" + "type": "string", + "format": "uri" } }, "required": [ @@ -397,6 +440,7 @@ "unevaluatedProperties": false }, "parameter": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#parameter-object", "type": "object", "properties": { "name": { @@ -421,18 +465,17 @@ "default": false, "type": "boolean" }, - "allowEmptyValue": { - "default": false, - "type": "boolean" - }, "schema": { "$dynamicRef": "#meta" }, "content": { - "$ref": "#/$defs/content" + "$ref": "#/$defs/content", + "minProperties": 1, + "maxProperties": 1 } }, "required": [ + "name", "in" ], "oneOf": [ @@ -447,6 +490,24 @@ ] } ], + "if": { + "properties": { + "in": { + "const": "query" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "allowEmptyValue": { + "default": false, + "type": "boolean" + } + } + }, "dependentSchemas": { "schema": { "properties": { @@ -455,10 +516,6 @@ }, "explode": { "type": "boolean" - }, - "allowReserved": { - "default": false, - "type": "boolean" } }, "allOf": [ @@ -495,6 +552,9 @@ }, "then": { "properties": { + "name": { + "pattern": "[^/#?]+$" + }, "style": { "default": "simple", "enum": [ @@ -527,9 +587,7 @@ "properties": { "style": { "default": "simple", - "enum": [ - "simple" - ] + "const": "simple" } } } @@ -555,6 +613,10 @@ "pipeDelimited", "deepObject" ] + }, + "allowReserved": { + "default": false, + "type": "boolean" } } } @@ -574,9 +636,7 @@ "properties": { "style": { "default": "form", - "enum": [ - "form" - ] + "const": "form" } } } @@ -615,6 +675,7 @@ }, "parameter-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -627,6 +688,7 @@ } }, "request-body": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#request-body-object", "type": "object", "properties": { "description": { @@ -648,6 +710,7 @@ }, "request-body-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -660,6 +723,7 @@ } }, "content": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#fixed-fields-10", "type": "object", "additionalProperties": { "$ref": "#/$defs/media-type" @@ -669,6 +733,7 @@ } }, "media-type": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#media-type-object", "type": "object", "properties": { "schema": { @@ -692,6 +757,7 @@ "unevaluatedProperties": false }, "encoding": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#encoding-object", "type": "object", "properties": { "contentType": { @@ -760,6 +826,7 @@ } }, "responses": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#responses-object", "type": "object", "properties": { "default": { @@ -767,14 +834,16 @@ } }, "patternProperties": { - "^[1-5][0-9X]{2}$": { + "^[1-5](?:[0-9]{2}|XX)$": { "$ref": "#/$defs/response-or-reference" } }, + "minProperties": 1, "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "response": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#response-object", "type": "object", "properties": { "description": { @@ -804,6 +873,7 @@ }, "response-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -816,6 +886,7 @@ } }, "callbacks": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#callback-object", "type": "object", "$ref": "#/$defs/specification-extensions", "additionalProperties": { @@ -824,6 +895,7 @@ }, "callbacks-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -836,6 +908,7 @@ } }, "example": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#example-object", "type": "object", "properties": { "summary": { @@ -846,14 +919,22 @@ }, "value": true, "externalValue": { - "$ref": "#/$defs/uri" + "type": "string", + "format": "uri" } }, + "not": { + "required": [ + "value", + "externalValue" + ] + }, "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "example-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -866,12 +947,16 @@ } }, "link": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#link-object", "type": "object", "properties": { "operationRef": { - "$ref": "#/$defs/uri" + "type": "string", + "format": "uri-reference" + }, + "operationId": { + "type": "string" }, - "operationId": true, "parameters": { "$ref": "#/$defs/map-of-strings" }, @@ -900,6 +985,7 @@ }, "link-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -912,6 +998,7 @@ } }, "header": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#header-object", "type": "object", "properties": { "description": { @@ -925,40 +1012,40 @@ "default": false, "type": "boolean" }, - "allowEmptyValue": { - "default": false, - "type": "boolean" + "schema": { + "$dynamicRef": "#meta" + }, + "content": { + "$ref": "#/$defs/content", + "minProperties": 1, + "maxProperties": 1 } }, + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ] + } + ], "dependentSchemas": { "schema": { "properties": { "style": { "default": "simple", - "enum": [ - "simple" - ] + "const": "simple" }, "explode": { "default": false, "type": "boolean" - }, - "allowReserved": { - "default": false, - "type": "boolean" - }, - "schema": { - "$dynamicRef": "#meta" } }, "$ref": "#/$defs/examples" - }, - "content": { - "properties": { - "content": { - "$ref": "#/$defs/content" - } - } } }, "$ref": "#/$defs/specification-extensions", @@ -966,6 +1053,7 @@ }, "header-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -978,6 +1066,7 @@ } }, "tag": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#tag-object", "type": "object", "properties": { "name": { @@ -997,10 +1086,12 @@ "unevaluatedProperties": false }, "reference": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#reference-object", "type": "object", "properties": { "$ref": { - "$ref": "#/$defs/uri" + "type": "string", + "format": "uri-reference" }, "summary": { "type": "string" @@ -1012,6 +1103,7 @@ "unevaluatedProperties": false }, "schema": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#schema-object", "$dynamicAnchor": "meta", "type": [ "object", @@ -1019,6 +1111,7 @@ ] }, "security-scheme": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#security-scheme-object", "type": "object", "properties": { "type": { @@ -1118,7 +1211,8 @@ "const": "http" }, "scheme": { - "const": "bearer" + "type": "string", + "pattern": "^[Bb][Ee][Aa][Rr][Ee][Rr]$" } }, "required": [ @@ -1131,10 +1225,7 @@ "bearerFormat": { "type": "string" } - }, - "required": [ - "scheme" - ] + } } }, "type-oauth2": { @@ -1173,7 +1264,8 @@ "then": { "properties": { "openIdConnectUrl": { - "$ref": "#/$defs/uri" + "type": "string", + "format": "uri" } }, "required": [ @@ -1185,6 +1277,7 @@ }, "security-scheme-or-reference": { "if": { + "type": "object", "required": [ "$ref" ] @@ -1219,10 +1312,12 @@ "type": "object", "properties": { "authorizationUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "refreshUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "scopes": { "$ref": "#/$defs/map-of-strings" @@ -1239,10 +1334,12 @@ "type": "object", "properties": { "tokenUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "refreshUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "scopes": { "$ref": "#/$defs/map-of-strings" @@ -1259,10 +1356,12 @@ "type": "object", "properties": { "tokenUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "refreshUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "scopes": { "$ref": "#/$defs/map-of-strings" @@ -1279,13 +1378,16 @@ "type": "object", "properties": { "authorizationUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "tokenUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "refreshUrl": { - "type": "string" + "type": "string", + "format": "uri" }, "scopes": { "$ref": "#/$defs/map-of-strings" @@ -1302,6 +1404,7 @@ } }, "security-requirement": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#security-requirement-object", "type": "object", "additionalProperties": { "type": "array", @@ -1311,6 +1414,7 @@ } }, "specification-extensions": { + "$comment": "https://spec.openapis.org/oas/v3.1.0#specification-extensions", "patternProperties": { "^x-": true } @@ -1326,10 +1430,6 @@ } } }, - "uri": { - "type": "string", - "format": "uri" - }, "map-of-strings": { "type": "object", "additionalProperties": { diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 9b71e11031..331bba0813 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -1,6 +1,8 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +$id: 'https://spec.openapis.org/oas/3.1/schema/2022-10-07' $schema: 'https://json-schema.org/draft/2020-12/schema' +description: The description of OpenAPI v3.1.x documents without schema validation, as defined by https://spec.openapis.org/oas/v3.1.0 + type: object properties: openapi: @@ -9,10 +11,15 @@ properties: info: $ref: '#/$defs/info' jsonSchemaDialect: - $ref: '#/$defs/uri' + type: string + format: uri default: 'https://spec.openapis.org/oas/3.1/dialect/base' servers: - $ref: '#/$defs/server' + type: array + items: + $ref: '#/$defs/server' + default: + - url: / paths: $ref: '#/$defs/paths' webhooks: @@ -46,6 +53,7 @@ unevaluatedProperties: false $defs: info: + $comment: https://spec.openapis.org/oas/v3.1.0#info-object type: object properties: title: @@ -56,6 +64,7 @@ $defs: type: string termsOfService: type: string + format: uri contact: $ref: '#/$defs/contact' license: @@ -69,18 +78,22 @@ $defs: unevaluatedProperties: false contact: + $comment: https://spec.openapis.org/oas/v3.1.0#contact-object type: object properties: name: type: string url: type: string + format: uri email: type: string + format: email $ref: '#/$defs/specification-extensions' unevaluatedProperties: false license: + $comment: https://spec.openapis.org/oas/v3.1.0#license-object type: object properties: name: @@ -88,22 +101,25 @@ $defs: identifier: type: string url: - $ref: '#/$defs/uri' + type: string + format: uri required: - name - oneOf: - - required: - - identifier - - required: - - url + dependentSchemas: + identifier: + not: + required: + - url $ref: '#/$defs/specification-extensions' unevaluatedProperties: false server: + $comment: https://spec.openapis.org/oas/v3.1.0#server-object type: object properties: url: - $ref: '#/$defs/uri' + type: string + format: uri-reference description: type: string variables: @@ -116,6 +132,7 @@ $defs: unevaluatedProperties: false server-variable: + $comment: https://spec.openapis.org/oas/v3.1.0#server-variable-object type: object properties: enum: @@ -125,7 +142,7 @@ $defs: minItems: 1 default: type: string - descriptions: + description: type: string required: - default @@ -133,6 +150,7 @@ $defs: unevaluatedProperties: false components: + $comment: https://spec.openapis.org/oas/v3.1.0#components-object type: object properties: schemas: @@ -184,6 +202,7 @@ $defs: unevaluatedProperties: false paths: + $comment: https://spec.openapis.org/oas/v3.1.0#paths-object type: object patternProperties: '^/': @@ -192,6 +211,7 @@ $defs: unevaluatedProperties: false path-item: + $comment: https://spec.openapis.org/oas/v3.1.0#path-item-object type: object properties: summary: @@ -206,14 +226,28 @@ $defs: type: array items: $ref: '#/$defs/parameter-or-reference' - patternProperties: - '^(get|post|delete|options|head|patch|trace)$': + get: + $ref: '#/$defs/operation' + put: + $ref: '#/$defs/operation' + post: + $ref: '#/$defs/operation' + delete: + $ref: '#/$defs/operation' + options: + $ref: '#/$defs/operation' + head: + $ref: '#/$defs/operation' + patch: + $ref: '#/$defs/operation' + trace: $ref: '#/$defs/operation' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false path-item-or-reference: if: + type: object required: - $ref then: @@ -222,6 +256,7 @@ $defs: $ref: '#/$defs/path-item' operation: + $comment: https://spec.openapis.org/oas/v3.1.0#operation-object type: object properties: tags: @@ -263,18 +298,21 @@ $defs: unevaluatedProperties: false external-documentation: + $comment: https://spec.openapis.org/oas/v3.1.0#external-documentation-object type: object properties: description: type: string url: - $ref: '#/$defs/uri' + type: string + format: uri required: - url $ref: '#/$defs/specification-extensions' unevaluatedProperties: false parameter: + $comment: https://spec.openapis.org/oas/v3.1.0#parameter-object type: object properties: name: @@ -293,20 +331,31 @@ $defs: deprecated: default: false type: boolean - allowEmptyValue: - default: false - type: boolean schema: $dynamicRef: '#meta' content: $ref: '#/$defs/content' + minProperties: 1 + maxProperties: 1 required: + - name - in oneOf: - required: - schema - required: - content + if: + properties: + in: + const: query + required: + - in + then: + properties: + allowEmptyValue: + default: false + type: boolean dependentSchemas: schema: properties: @@ -314,9 +363,6 @@ $defs: type: string explode: type: boolean - allowReserved: - default: false - type: boolean allOf: - $ref: '#/$defs/examples' - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path' @@ -335,6 +381,8 @@ $defs: - in then: properties: + name: + pattern: '[^/#?]+$' style: default: simple enum: @@ -357,8 +405,7 @@ $defs: properties: style: default: simple - enum: - - simple + const: simple styles-for-query: if: @@ -376,7 +423,9 @@ $defs: - spaceDelimited - pipeDelimited - deepObject - + allowReserved: + default: false + type: boolean styles-for-cookie: if: properties: @@ -388,8 +437,7 @@ $defs: properties: style: default: form - enum: - - form + const: form styles-for-form: if: @@ -412,6 +460,7 @@ $defs: parameter-or-reference: if: + type: object required: - $ref then: @@ -420,6 +469,7 @@ $defs: $ref: '#/$defs/parameter' request-body: + $comment: https://spec.openapis.org/oas/v3.1.0#request-body-object type: object properties: description: @@ -436,6 +486,7 @@ $defs: request-body-or-reference: if: + type: object required: - $ref then: @@ -444,6 +495,7 @@ $defs: $ref: '#/$defs/request-body' content: + $comment: https://spec.openapis.org/oas/v3.1.0#fixed-fields-10 type: object additionalProperties: $ref: '#/$defs/media-type' @@ -451,6 +503,7 @@ $defs: format: media-range media-type: + $comment: https://spec.openapis.org/oas/v3.1.0#media-type-object type: object properties: schema: @@ -465,6 +518,7 @@ $defs: unevaluatedProperties: false encoding: + $comment: https://spec.openapis.org/oas/v3.1.0#encoding-object type: object properties: contentType: @@ -509,17 +563,20 @@ $defs: default: false responses: + $comment: https://spec.openapis.org/oas/v3.1.0#responses-object type: object properties: default: $ref: '#/$defs/response-or-reference' patternProperties: - '^[1-5][0-9X]{2}$': + '^[1-5](?:[0-9]{2}|XX)$': $ref: '#/$defs/response-or-reference' + minProperties: 1 $ref: '#/$defs/specification-extensions' unevaluatedProperties: false response: + $comment: https://spec.openapis.org/oas/v3.1.0#response-object type: object properties: description: @@ -541,6 +598,7 @@ $defs: response-or-reference: if: + type: object required: - $ref then: @@ -549,6 +607,7 @@ $defs: $ref: '#/$defs/response' callbacks: + $comment: https://spec.openapis.org/oas/v3.1.0#callback-object type: object $ref: '#/$defs/specification-extensions' additionalProperties: @@ -556,6 +615,7 @@ $defs: callbacks-or-reference: if: + type: object required: - $ref then: @@ -564,6 +624,7 @@ $defs: $ref: '#/$defs/callbacks' example: + $comment: https://spec.openapis.org/oas/v3.1.0#example-object type: object properties: summary: @@ -572,12 +633,18 @@ $defs: type: string value: true externalValue: - $ref: '#/$defs/uri' + type: string + format: uri + not: + required: + - value + - externalValue $ref: '#/$defs/specification-extensions' unevaluatedProperties: false example-or-reference: if: + type: object required: - $ref then: @@ -586,11 +653,14 @@ $defs: $ref: '#/$defs/example' link: + $comment: https://spec.openapis.org/oas/v3.1.0#link-object type: object properties: operationRef: - $ref: '#/$defs/uri' - operationId: true + type: string + format: uri-reference + operationId: + type: string parameters: $ref: '#/$defs/map-of-strings' requestBody: true @@ -608,6 +678,7 @@ $defs: link-or-reference: if: + type: object required: - $ref then: @@ -616,6 +687,7 @@ $defs: $ref: '#/$defs/link' header: + $comment: https://spec.openapis.org/oas/v3.1.0#header-object type: object properties: description: @@ -626,34 +698,33 @@ $defs: deprecated: default: false type: boolean - allowEmptyValue: - default: false - type: boolean + schema: + $dynamicRef: '#meta' + content: + $ref: '#/$defs/content' + minProperties: 1 + maxProperties: 1 + oneOf: + - required: + - schema + - required: + - content dependentSchemas: schema: properties: style: default: simple - enum: - - simple + const: simple explode: default: false type: boolean - allowReserved: - default: false - type: boolean - schema: - $dynamicRef: '#meta' $ref: '#/$defs/examples' - content: - properties: - content: - $ref: '#/$defs/content' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false header-or-reference: if: + type: object required: - $ref then: @@ -662,6 +733,7 @@ $defs: $ref: '#/$defs/header' tag: + $comment: https://spec.openapis.org/oas/v3.1.0#tag-object type: object properties: name: @@ -676,10 +748,12 @@ $defs: unevaluatedProperties: false reference: + $comment: https://spec.openapis.org/oas/v3.1.0#reference-object type: object properties: $ref: - $ref: '#/$defs/uri' + type: string + format: uri-reference summary: type: string description: @@ -687,12 +761,14 @@ $defs: unevaluatedProperties: false schema: + $comment: https://spec.openapis.org/oas/v3.1.0#schema-object $dynamicAnchor: meta type: - object - boolean security-scheme: + $comment: https://spec.openapis.org/oas/v3.1.0#security-scheme-object type: object properties: type: @@ -756,7 +832,8 @@ $defs: type: const: http scheme: - const: bearer + type: string + pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$ required: - type - scheme @@ -764,8 +841,6 @@ $defs: properties: bearerFormat: type: string - required: - - scheme type-oauth2: if: @@ -791,12 +866,14 @@ $defs: then: properties: openIdConnectUrl: - $ref: '#/$defs/uri' + type: string + format: uri required: - openIdConnectUrl security-scheme-or-reference: if: + type: object required: - $ref then: @@ -824,8 +901,10 @@ $defs: properties: authorizationUrl: type: string + format: uri refreshUrl: type: string + format: uri scopes: $ref: '#/$defs/map-of-strings' required: @@ -839,8 +918,10 @@ $defs: properties: tokenUrl: type: string + format: uri refreshUrl: type: string + format: uri scopes: $ref: '#/$defs/map-of-strings' required: @@ -854,8 +935,10 @@ $defs: properties: tokenUrl: type: string + format: uri refreshUrl: type: string + format: uri scopes: $ref: '#/$defs/map-of-strings' required: @@ -869,10 +952,13 @@ $defs: properties: authorizationUrl: type: string + format: uri tokenUrl: type: string + format: uri refreshUrl: type: string + format: uri scopes: $ref: '#/$defs/map-of-strings' required: @@ -883,6 +969,7 @@ $defs: unevaluatedProperties: false security-requirement: + $comment: https://spec.openapis.org/oas/v3.1.0#security-requirement-object type: object additionalProperties: type: array @@ -890,6 +977,7 @@ $defs: type: string specification-extensions: + $comment: https://spec.openapis.org/oas/v3.1.0#specification-extensions patternProperties: '^x-': true @@ -901,10 +989,6 @@ $defs: additionalProperties: $ref: '#/$defs/example-or-reference' - uri: - type: string - format: uri - map-of-strings: type: object additionalProperties: diff --git a/scripts/fwdabort.sh b/scripts/fwdabort.sh new file mode 100755 index 0000000000..ccec20bfbe --- /dev/null +++ b/scripts/fwdabort.sh @@ -0,0 +1,10 @@ +#!/bin/sh + +# Aborts a fwdport.sh run cleanly + +# Author: @MikeRalphson + +git am -i --abort +rm -f *.mbox *.patch *.rej +git checkout main + diff --git a/scripts/fwdport.sh b/scripts/fwdport.sh new file mode 100755 index 0000000000..efe20ca6ed --- /dev/null +++ b/scripts/fwdport.sh @@ -0,0 +1,100 @@ +#!/bin/sh + +# Forward ports changes from the spec file of a source branch to the spec file of a target branch +# For example: porting interim changes made in v3.1.x patch releases to the v3.2.0 branch + +# This script is designed to be run once per branch, when interim changes need merging in +# before another branch is released. It is not intended to be run multiple times to keep +# two branches in sync. + +# Author: @MikeRalphson +# Issues: https://github.com/OAI/OpenAPI-Specification/pull/2163 + +mainbranch=main +myremote=origin +upstream=upstream + +source=$1 +target=$2 + +if [ -z "$source" ]; then + echo You must specify a source and target branch + exit 1 +fi +if [ -z "$target" ]; then + echo You must specify a source and target branch + exit 1 +fi + +echo Checking working dir... +status=`git ls-files -m` +if [ -z "$status" ]; then + echo All clear +else + echo You have a dirty working tree, aborting + echo ${status} + exit 1 +fi + +cruft=`ls -1 *.patch *.rej *.mbox 2>/dev/null` +if [ -z "$cruft" ]; then + echo No .patch, .rej or .mbox files found, continuing +else + echo .patch / .rej / .mbox files found, aborting + exit 1 +fi + +tmpbranch=forward-port-${source} +existing=`git branch | grep ${tmpbranch}` +if [ -z "$existing" ]; then + echo No matching temp branch found, continuing +else + echo Temp branch ${tmpbranch} already exists, aborting + exit 1 +fi + +srcver=`echo $source | sed s/-dev//g | sed s/v//g`.md +tgtver=`echo $target | sed s/-dev//g | sed s/v//g`.md + +echo Forward-porting changes from ${source}:versions/${srcver} to ${target}:${tgtver} +echo You may use the commands \'git fwdskip\' and \'git fwdcont\' to skip patches, or to continue after manually fixing. +echo Use `fwdabort.sh` to abort cleanly. +echo +echo Due to a bug in \`git am\`, git v2.22.1+ is required, you\'re running: +git --version +echo +echo Press a key to continue... +read + +git config --add rerere.enabled true +git config alias.fwdskip '!git am -i --skip' +git config alias.fwdcont '!git am -i --continue' + +git checkout ${source} +git pull ${upstream} ${source} + +# look at using git merge-base as an alternative? say if we branched 3.1.0 part way through 3.0.2's life + +firstsrc=`git log --abbrev-commit --format=format:%H -n 1 --reverse -- versions/${srcver}` +lastsrc=`git log --abbrev-commit --format=format:%H -- versions/${srcver} | tail -n 1` +changes=`git log --format=format:%H --reverse versions/${srcver}` + +echo Applying changes from ${firstsrc} to ${lastsrc} + +# remove first (creation) commit and uniq without sorting +oIFS="$IFS" +IFS=' ' +changes=`echo ${changes} | tail -n +2 | awk '!x[$0]++'` +IFS="$oIFS" + +for c in ${changes}; do + git format-patch --stdout -1 $c | sed s/${srcver}/${tgtver}/g > $c.patch +done + +git checkout ${target} +git pull ${upstream} ${target} +git checkout -b ${tmpbranch} +cat *.patch > fwdport.mbox +rm -f *.patch +git am -3 --interactive --ignore-whitespace -s fwdport.mbox + 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..13f5fc82f7 --- /dev/null +++ b/scripts/md2html/build.sh @@ -0,0 +1,33 @@ +#!/bin/bash + +# Author: @MikeRalphson + +# run this script from the root of the repo. It is designed to be run by a GitHub workflow. +# It contains bashisms + +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` +latestCopied=none +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 + latestCopied=v$version + fi + fi +done +echo Latest tag is $latest, copied $latestCopied to latest.html + 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..ae7a501967 --- /dev/null +++ b/scripts/md2html/md2html.js @@ -0,0 +1,315 @@ +/* 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 */ + +'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('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; +const abstract = 'What is the OpenAPI Specification?'; +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)}`; + + // SEO + preface += ''; + preface += ''; + + if (options.respec) { + preface += ''; + preface += ``; + preface += fs.readFileSync('./analytics/google.html','utf8'); + preface += ''; + preface += ''; + preface += `

${title.split('|')[0]}

`; + preface += `
`; + preface += 'The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP 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 result = new Date(); + let h = md.render(m); + let $ = cheerio.load(h); + $('table').each(function(i,table){ + const h = $(table).find('th'); + const headers = []; + $(h).each(function(i,header){ + headers.push($(header).text()); + }); + if (headers.length >= 2 && headers[0] === 'Version' && headers[1] === 'Date') { + let c = $(table).find('tr').find('td'); + let v = $(c[0]).text(); + let d = $(c[1]).text(); + argv.subtitle = v; + if (d !== 'TBA') result = new Date(d); + } + }); + return result; +} + +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('