Introducing OpenAPI Version 3.1
Download as PPTX, PDF0 likes1,021 views
The document provides an overview of OpenAPI 3.1, detailing its history, versioning using semantic versioning, and changes from previous versions. It introduces new features like webhooks, security schemes for client certificates, and enhancements to support various content types and schemas. Additionally, it discusses future possibilities such as overlays and reusable components for more efficient API design.
Introducing OpenAPI Version 3.1
- 1. Introduction to OpenAPI 3.1 Darrel Miller Ron Ratovsky OAI Technical Steering Committee Members
- 4. Proprietary & Confidential 4 OpenAPI 2.0 2014 2015 2016 2017 OpenAPI 3.0 OpenAPI 3.0.2 2018 2019 Alternative Schema Pilot OpenAPI 3.1 2021 Overlays OpenAPI Specification History
- 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
- 10. Proprietary & Confidential 10 OpenAPI Documents paths webhooks components
- 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
- 12. Proprietary & Confidential 12 OpenAPI & JSON Schema OpenAPI 3.0 OpenAPI Schema OpenAPI Tools JSON Schema Tools OpenAPI 3.1 JSON Schema Draft 2020-09 OpenAPI Tools JSON Schema Tools Partially Broken OpenAPI Schema Tools
- 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
- 14. Proprietary & Confidential 14 Relative References URIs (relative to document) • Reference Object • Path Item Object • $ref • Link Object • operationRef URLs (relative to servers) • External Documentation • License • Security URLs
- 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)