Successfully reported this slideshow.

Introducing OpenAPI Version 3.1

0

Share

Upcoming SlideShare
RAML
RAML
Loading in …3
×
1 of 15
1 of 15

Introducing OpenAPI Version 3.1

0

Share

Download to read offline

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.

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.

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

Related Audiobooks

Free with a 14 day trial from Scribd

See all

Introducing OpenAPI Version 3.1

  1. 1. Introduction to OpenAPI 3.1 Darrel Miller Ron Ratovsky OAI Technical Steering Committee Members
  2. 2. Proprietary & Confidential 3 OpenAPI 3.1
  3. 3. 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
  4. 4. 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!
  5. 5. 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
  6. 6. 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
  7. 7. 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
  8. 8. 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
  9. 9. Proprietary & Confidential 10 OpenAPI Documents paths webhooks components
  10. 10. 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
  11. 11. 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
  12. 12. 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
  13. 13. 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
  14. 14. 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)

Editor's Notes

  • Member of TSC
  • Easy to migrate existing body of descriptions to new version
    SemVer sucks for specs! Major and minor
  • -45
  • ×