Skip to content

Commit

Permalink
v3.1.0-rc0 Release (#2251)
Browse files Browse the repository at this point in the history
* 3.1.0 prep

* Update README

* Allow specification extensions in discriminator object

* Note that specification extensions beginning x-oas- are reserved

* security; add mutualTLS securityScheme type

* 832 add info.summary (#1779)

* Fix: #832. Add info.summary.

* Fix: summary is shord, description is verbose.

Be consistent with other definitions of summary and description.

* fix OIDC url and OAuth2 requirements

Signed-off-by: Axel Nennker <axel.nennker@telekom.de>

* Update Schema Object to proper JSON Schema

* update vocab and arbitrary props

* another go at arbitrary keywords

* feedback from @handrews

* Support style, explode, allowReserved encoding for multipart/form-data (#2066)

* Extend style, explode, allowReserved in encoding to multipart-formdata (#2018)

* Update versions/3.1.0.md

Co-Authored-By: Ron <ron@swagger.io>

* Replace details of multipart/form-data format with referce to RFC 7578

* Update versions/3.1.0.md

Co-Authored-By: Darrel <darrmi@microsoft.com>

* default should match json schema

* removed json schema keyworld list, its just all of em.

* redundant $ref reference

* Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects.

* Add support for webhooks as a top-level element (#2103)

* Add webhooks as a top-level element to the spec

* Add the changes from #2048 and signpost webhooks

* Add an example of webhooks

* Relocate and expand on webhooks section following feedback

* Better wording to describe expectations on API consumers

* Clearer wording for why the paths element is here

* Update language to make callbacks clearer

* Align the OAS 3.1 nullable language with the 3.0.3 (#2115)

This adapts the language from PR #2046, with minimal wording tweaks
to account for type now being able to have multiple values (type arrays).

* allow, but discourage, requestBody for GET, HEAD, DELETE (#2117)

* Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#2107)

* Checkpoint of draft

* Fix typo.

Co-Authored-By: Darrel <darrmi@microsoft.com>

* Fix plural anchor

Co-Authored-By: Mike Ralphson <mike.ralphson@gmail.com>

* Remove superfluous specification

Co-Authored-By: Phil Sturgeon <me@philsturgeon.uk>

Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com>
Co-authored-by: Phil Sturgeon <me@philsturgeon.uk>

* Fix table cell formatting containing `nullable` description (#2152)

* Add SPDX identifier field to license object, fixes #1599 (#2105)

* Add information about objects to the description too

* Make paths object optional (#1781)

* Make paths object optional

* Adding reusable Path Item Objects

Under `components`

* Adopt DM's suggested change to OpenAPI doc definition

* Cleanup use of specification and definition where we mean document

* multipartite>composite, define ACL

* Add ' | Reference Object' to callbacks/webhooks

Co-authored-by: Ron <ron@swagger.io>

* Fwd port v3.0.3 dev to v3.1.0 dev (#2163)

* fix typo in Callback Object

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* retain typo in v3.0.2; fix for v3.0.3 (#1899)

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Clarify empty Security Requirement Object usage and validity (#1886)

* Clarify empty Security Requirement Object usage and validity

* Reorder sentences to make clearer.

* Remove wrong text.

* Removed unneeded text.

Co-authored-by: Ron <ron@swagger.io>
Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Ron's wording for Darrels feedback

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* ted updates

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Replace 'application' by 'API' within the 'Info Object' definition. (#2004)

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Path Templating Clarification - proposed fix for #1830. (#1831)

* Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter.

* #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter.

* Update #1830 fix with suggestion from Darrel

@darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea.

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* yaml.org supports https, but www.yaml.org is misconfigured

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Updated text for OperationRef

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* fix a typo in the Security Filtering section (#1837)

* fix a typo in the Security Filtering section

* Security filtering slight reword

Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com>
Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Make ABNF for runtime expressions complete

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Explain unclear semantics of property `$ref` in Path Item Object (#1964)

* Explain unclear semantics of property `$ref` in Path Item Object

Currently, as explained in #1038 (comment) the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear.

* Update versions/3.1.0.md

Co-authored-by: Ron <ron@swagger.io>
Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Clarify constraints on Security Scheme Object Scheme Property (#1880)

* Wording around scheme extensions

* Clarified that securitySchemeScheme is only a SHOULD be registered scheme

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* fix difference between yaml and json in Response Object Examples

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Server Variable Object clarifications (#1809)

* Server Variable Object clarifications

* Toned language down for proper semver versioning

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Fix formatting errors in example (#2132)

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Update 3.0.3 for release (#2149)

* Update README.md for release

* Update release date for 3.0.3

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Update versions/3.1.0.md

Co-Authored-By: Darrel <darrmi@microsoft.com>
Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Fixed typo

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* explicit 'forward slash'

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* fix #2053: `style` keyword is not supported inside Schema object

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* OpenAPI not Open API

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* backticks

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* minor clarification for operationId usage in link objects (#1733)

* minor clarification

it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit.

* use right terminology

Co-Authored-By: Mike Ralphson <mike.ralphson@gmail.com>

Co-authored-by: Ron <ron@swagger.io>
Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com>
Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Update 3.1.0.md

fixed typo

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Removed confusing comment

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Clarify the spec to allow optional or unspecified OAuth scopes (#1888)

* Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all.

* Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed.

* For #513, adjusting language and removing examples

For #513, adjusting language and removing examples as suggested by @webron.

* removed unnecessary example header

Co-authored-by: Ron <ron@swagger.io>
Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* The examples keyword is not supported inside schema (#2042)

* examples not supported inside schema

* figured it out

* a tiny little edit

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006)

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

* Fix formatting errors in example (#2132)

Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com>

Co-authored-by: seiya <r108338@yahoo.co.jp>
Co-authored-by: Adam Leventhal <ahl@transposit.com>
Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>
Co-authored-by: Ron <ron@swagger.io>
Co-authored-by: Phil Sturgeon <me@philsturgeon.uk>
Co-authored-by: Patrice Krakow <patrice.krakow@gmail.com>
Co-authored-by: Ted Epstein <ted.epstein@reprezen.com>
Co-authored-by: Darrel Miller <darrmi@microsoft.com>
Co-authored-by: Carsten Brandt <mail@cebe.cc>
Co-authored-by: Henry Andrews <andrews_henry@yahoo.com>
Co-authored-by: Sergej <sergej2705@users.noreply.github.com>
Co-authored-by: nasa9084 <nasa.9084.bassclarinet@gmail.com>
Co-authored-by: Erik Wilde <dret@users.noreply.github.com>

* security; widen use of scopes array to other securityScheme types (#1829)

Co-authored-by: Ron <ron@swagger.io>

* Allow summary and description as $ref siblings (#2181)

* HTTP not REST (#1946)

Co-authored-by: Phil Sturgeon <me@philsturgeon.uk>

* Missing updates

While going over the changes for the release notes, found two issues:
- The TOC entry for `Relative references in URIs` was not modified to match the change in the spec.
- The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays).

* Remove boolean compatibility for exclusive* (#2226)

This brings exclusiveMinimum, exclusiveMaximum, minimum, and
maximum, into full modern JSON Schema compatibility.

There are no edits directly mentioning minimum and maximum,
but removing the boolean form simplifies their processing
by making it context-independent.

* Update "format" and "content*" for new JSON Schema (#2200)

* Update "format" and "content*" for new JSON Schema

This removes OAS formats and examples that are now superfluous
as they are part of the 2019-09 JSON Schema draft.

Similarly it deprecates the "byte" and "binary" formats in favor
of JSON Schema's "contentEncoding" and "contentMediaType" keywords,
and updates various related exapmles and other guidance.

It also removes confusingly blank rows in the OAS format table.

* "format" is an annotation

* Fix broken table, type, in Encoding Object

Broke some things while updating for "content*"

* Fix format of `format`

Backticks, not double quotes.

* Remove unneeded detail on "format"

This was just duplicating info from the JSON Schema spec.

Co-authored-by: Darrel <darrmi@microsoft.com>

* Remove "byte" and "binary" formats altogether.

Instead of just deprecating.  The "content*" keywords now
cover these use cases.

* Harmonize JSON Schema content* + Media Type Object

Includes harmonizing with the Encoding Object.  In general,
OpenAPI objects set the media type, although there is a case
for `contentMediaType` with multipart/form-data.  Otherwise,
`contentEncoding` replaces the now-removed custom formats.

A possibly controversial change is to indicate unencoded binary
data by omitting `type` (or omitting the schema altogether), as
binary data does not conform to JSON string requirements.

This could still be done with `type: string` if that is preferred.
It's going to be a bit weird either way.

I can add wording in the next JSON Schema draft to clarify
whichever approach makes more sense.

* Fix typos from review

* Remove stray {}

* Fix inconsistencies contentMediaType and Encoding Object

Co-authored-by: Darrel <darrmi@microsoft.com>

* [3.1.0-dev] drop OAS semver requirement (#2243)

* drop OAS semver requirement

* Update versions/3.1.0.md

Co-authored-by: Darrel <darrmi@microsoft.com>

* Remove "nullable" entirely (#2246)

* Update version for release (#2269)

Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com>
Co-authored-by: Roberto Polli <robipolli@gmail.com>
Co-authored-by: Axel Nennker <axel.nennker@telekom.de>
Co-authored-by: Phil Sturgeon <me@philsturgeon.uk>
Co-authored-by: Mike Kistler <mkistler@us.ibm.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Arhimenrius <arhimenrius@gmail.com>
Co-authored-by: Lorna Jane Mitchell <lorna@lornajane.net>
Co-authored-by: Henry Andrews <andrews_henry@yahoo.com>
Co-authored-by: Alan Crosswell <alan@crosswell.us>
Co-authored-by: Helen Kosova <hkosova@users.noreply.github.com>
Co-authored-by: seiya <r108338@yahoo.co.jp>
Co-authored-by: Adam Leventhal <ahl@transposit.com>
Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>
Co-authored-by: Patrice Krakow <patrice.krakow@gmail.com>
Co-authored-by: Ted Epstein <ted.epstein@reprezen.com>
Co-authored-by: Carsten Brandt <mail@cebe.cc>
Co-authored-by: Sergej <sergej2705@users.noreply.github.com>
Co-authored-by: nasa9084 <nasa.9084.bassclarinet@gmail.com>
Co-authored-by: Erik Wilde <dret@users.noreply.github.com>
Co-authored-by: Marsh Gardiner <marsh.gardiner@gmail.com>
Co-authored-by: Phil Sturgeon <me@philsturgeon.com>
  • Loading branch information
1 parent 52f4e1a commit a5aad2b
Show file tree
Hide file tree
Showing 3 changed files with 3,502 additions and 3 deletions.
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,17 @@

![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200)


**This is the WIP branch for the next minor version of the spec - 3.1.0. Non-breaking changes should be submitted against this branch, specifically against [3.1.0.md](https://github.com/OAI/OpenAPI-Specification/blob/v3.1.0-dev/versions/3.1.0.md).**


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 [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer), 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, 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.

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 API's 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 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.

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 REST APIs. 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 REST API.
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.

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.

Expand Down
61 changes: 61 additions & 0 deletions examples/v3.1/webhook-example.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
openapi: 3.1.0
info:
title: Webhook Example
version: 1.0.0
paths:
# OpenAPI documents all need a paths element
/pets:
get:
summary: List all pets
operationId: listPets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"

webhooks:
# Each webhook needs a name
newPet:
# This is a Path Item Object, the only difference is that the request is initiated by the API provider
post:
requestBody:
description: Information about a new pet in the system
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
"200":
description: Return a 200 status to indicate that the data was received successfully

components:
schemas:
Pet:
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
Pets:
type: array
items:
$ref: "#/components/schemas/Pet"


Loading

0 comments on commit a5aad2b

Please sign in to comment.