With special guests Ron Ratovsky and Darrel Miller from the OpenAPI Initiative's Technical Steering Committee, this SmartBear webinar session covered the history of Swagger and the OpenAPI Specification, and all the latest changes in OAS 3.1.
5. Proprietary & Confidential
5
OpenAPI Versioning
3.0
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0
(semver) and follows the semver specification.
3.0.3
Each new minor version of the OpenAPI Specification SHALL allow any
OpenAPI document that is valid against any previous minor version of the
Specification, within the same major version, to be updated to the new
Specification version with equivalent semantics. Such an update MUST
only require changing the openapi property to the new minor version.
3.1
Occasionally, non-backwards compatible changes may be made in minor
versions of the OAS where impact is believed to be low relative to the
benefit provided.
Yay SemVer!
Clarity!
Err SemVer?
Need more
precision!
Boo SemVer!
6. Proprietary & Confidential
6
Info Object
https://spdx.org/licenses/
openapi: 3.1.0
info:
title: My Demo API
version: 1.0.0
summary: An API with examples of features in 3.1
license:
name: Apache 2.0
identifier: Apache-2.0 SPDX Identifier for machine
processing
7. Proprietary & Confidential
7
Webhooks
openapi: 3.1.0
info:
title: My Demo API
version: 1.0.0
summary: An API with examples of features in 3.1
webhooks:
newThingAlert:
$ref: '#/components/pathItems/newThingAlert'
components:
pathItems:
newThingAlert:
summary: Notification that a new thing has been created
post:
requestBody:
content:
applicaton/json:
schema:
type: object
properties:
thingName:
type: string
Reusable Path Items
Out-of-band registered
callbacks
8. Proprietary & Confidential
8
paths:
/todos:
post:
requestBody:
content:
application/json:
schema:
summary: A new todo object
description: |
This is where where a new todo
object can be described.
$ref: "#/components/schemas/todo“
responses:
201:
description: Created
components:
schemas:
todo:
title: A todo object
type: object
properties:
id:
type: integer
description:
type: string
$ref
SHOULD
override
Correction: The ability to override values
is only within the Reference Object and
cannot be used inside the Schema Object
9. Proprietary & Confidential
9
openapi: 3.1.0
info:
title: Security Demo
version: 1.0.0
paths:
/todos:
post:
...
security:
clientCertificate:
- todo.write
components:
securitySchemes:
clientCertificate:
type: mutualTLS
Security
Roles/Claims for non-OAuth
schemes
New security scheme type for client
certificates
11. Proprietary & Confidential
11
Odds and Ends Allowed request body for all HTTP methods
Added multipart/form-data support for encoding
object
Path Item parameters must be defined
Removed definition of some formats e.g. byte,
binary
Responses are now optional
13. Proprietary & Confidential
13
Full JSON Schema Support
- Full type support (nullable is gone)
- Formats are… not enforced
- exclusiveMinimum/Maximum, readOnly/writeOnly
- file uploads, contentEncoding, contentMediaType
- $schema and dialects (jsonSchemaDialect)
- $id
15. Proprietary & Confidential
15
The Future
Overlays: Separate document that augments another API description
Reusable groups: $ref more than one component
Alternative Schemas
Optional and Multi-segment Paths
Disambiguating based on query
Digital Signatures and Encryption
Discovery mechanism for security credentials (jwt, apikey, etc)
Hinweis der Redaktion
Member of TSC
Easy to migrate existing body of descriptions to new version
SemVer sucks for specs!Major and minor