What’s New in OpenAPI Specification 3.1

A presentation at APIDays Paris in December 2020 in by Lorna Jane Mitchell

Slide 1

Slide 1

The State of OpenAPI Specification: What’s New in 3.1 Lorna Mitchell, Vonage/OpenAPI Initiative

Slide 2

Slide 2

Quick Summary ● ● ● ● An OpenAPI minor release: 3.1 Full JSON Schema compatibility Webhooks are supported Many quality-of-life improvements @lornajane

Slide 3

Slide 3

Version Numbering ● ● From 3.1, OpenAPI does not follow Semantic Versioning Enables edge-case breakage for JSON Schema support @lornajane

Slide 4

Slide 4

JSON Schema OpenAPI 3.1 will support JSON Schema 2020-12

Slide 5

Slide 5

JSON Schema Data Types OpenAPI types are aligned with JSON Schema types – – – – – – string number object array boolean null @lornajane

Slide 6

Slide 6

JSON Schema Array of Types ● ● ● ● For 0elds that can have more than one type Arrays of types are supported Including null Breaking change: replaces nullable keyword parameters: - name: friendly-label in: query schema: type: string nullable: true parameters: - name: friendly-label in: query schema: type: - string - null @lornajane

Slide 7

Slide 7

JSON Schema Examples ● ● In schemas, recommend examples array, rather than example with a single element Both are valid in 3.1 schema: # 3.0 but valid in 3.1 required: - name properties: name: description: “Item name” type: “string” example: “Item One” schema: # Recommended in 3.1 required: - name properties: name: description: “Item name” type: “string” examples: - “Item One” @lornajane

Slide 8

Slide 8

Examples and Examples ● ● ● Look out for existing OpenAPI examples Used in Media Types section A map with named keys, rather than an array of values @lornajane

Slide 9

Slide 9

Examples and Examples responses: “400”: content: application/json: examples: throttled: summary: Limit exceeded value: status: “1” error_text: Throttled concurrent: summary: Request in progress value: request_id: abcdef0123456789abcdef0123456789 status: “10” error_text: Cannot start request, already in progress @lornajane

Slide 10

Slide 10

JSON Schema … Schemas ● Arbitrary keywords are supported components: schemas: style: type: object properties: template_id: type: number hue: type: string decoration: sparkly @lornajane

Slide 11

Slide 11

JSON Schema … Schemas ● Siblings are allowed alongside $ref content: ‘application/json’: schema: $ref: ‘#/components/schemas/style’ required: - hue @lornajane

Slide 12

Slide 12

Webhooks Built like callbacks

Slide 13

Slide 13

Callbacks Example ● Valid in 3.0 and 3.1 parameters: - $ref: “#/components/parameters/callback” responses: … callbacks: onData: “{$request.query.callback}”: post: operationId: asyncCallback requestBody: content: application/json: … responses: … @lornajane

Slide 14

Slide 14

Webhooks Example ● Newly introduced in 3.1 webhooks: inbound-sms: post: operationId: inbound-sms requestBody: content: application/json: … responses: … @lornajane

Slide 15

Slide 15

Webhooks Preview ● Use x-webhooks in 3.0 to see it working in Redoc @lornajane

Slide 16

Slide 16

OpenAPI Top-Level Elements 3.0 Required: Optional: ● openapi ● servers ● info ● tags ● paths ● security ● externalDocs ● components @lornajane

Slide 17

Slide 17

OpenAPI Top-Level Elements 3.0 Required: Optional: ● openapi ● servers ● info ● tags ● paths ● security ● externalDocs ● components @lornajane

Slide 18

Slide 18

OpenAPI Top-Level Elements 3.1 Required: One of: Optional: ● openapi ● paths ● servers ● info ● webhooks ● tags ● components ● security ● externalDocs @lornajane

Slide 19

Slide 19

OpenAPI Top-Level Elements 3.1 Required: One of: Optional: ● openapi ● paths ● servers ● info ● webhooks ● tags ● components ● security ● externalDocs @lornajane

Slide 20

Slide 20

Callback or Webhook? ● ● Overlapping concepts Example: subscription API call, later push events – – – a callback described within the subscription/con0guration API call a webhook alongside the paths that are functionally similar many incoming HTTP requests could be described either way @lornajane

Slide 21

Slide 21

Components Section ● ● 3.1 supports pathItems in components, to support webhooks and more use of callbacks Supported components section keys: – – – – – schemas responses parameters examples requestBodies – – – – – headers securitySchemas links callbacks pathItems @lornajane

Slide 22

Slide 22

OpenAPI Proposal Process ● ● ● Open proposal process Submit detailed proposal Attend meetings for feedback and champion your idea @lornajane

Slide 23

Slide 23

OpenAPI 3.1: Minor Improvements

Slide 24

Slide 24

Better $ref Benefits ● $ref can now have summary and description as siblings paths: /items: post: parameters: - $ref: ‘#/components/parameters/item’ description: The specific item in question @lornajane

Slide 25

Slide 25

Info Section Upgrade ● ● ● Add summary alongside title and description Summary is shown in list view, a brief summary Description is used in detail view and is more detailed @lornajane

Slide 26

Slide 26

License SPDX Identifier ● ● ● 3.0: license includes name and optional url 3.1: license includes name and optional url or identifier 0elds https://spdx.org/licenses/ @lornajane

Slide 27

Slide 27

MutualTLS Security Scheme ● 3.1 adds support for mutualTLS as a value for the security scheme type eld components: securitySchemes: bearerAuth: type: mutualTLS scheme: mutual @lornajane

Slide 28

Slide 28

Request Bodies for any Method ● ● ● 3.0 does not allow requestBody with GET or HEAD requests 3.1 allows it with any request Just because you can, doesn’t mean you should @lornajane

Slide 29

Slide 29

Responses are Optional ● ● Your OpenAPI 3.1 descriptions are valid without a responses 0eld for every endpoint Useful during development @lornajane

Slide 30

Slide 30

OpenAPI: Community Update

Slide 31

Slide 31

OpenAPI Documentation Project ● ● Getting started needs more than the spec Documentation initiative is well underway – https://oai.github.io/Documentation/ @lornajane

Slide 32

Slide 32

OpenAPI Involvement ● Everything happens in the open – ● ● https://github.com/OAI/OpenAPI-Speci0cation Regular meetings – ● Issues and PRs Meeting agenda is a GitHub issue Proposal process @lornajane

Slide 33

Slide 33

OpenAPI Tooling ● Tools improving all the time – https://openapi.tools/ @lornajane

Slide 34

Slide 34

State of OpenAPI ● ● ● ● ● Spec: Innovating, new release 3.1 Docs: Coming along nicely Tools: Levelling up, many more integrations Events: API Speci0cations Conference was in September Future: More meetings, get involved @lornajane

Slide 35

Slide 35

Resources ● https://github.com/OAI/OpenAPI-Speci0cation/blob/3.1.0-rc1/versions/3.1.0.md ● https://github.com/OAI/OpenAPI-Speci0cation/releases ● http://json-schema.org/ ● https://oai.github.io/Documentation/ ● https://github.com/OAI/OpenAPI-Speci0cation/ ● https://www.youtube.com/playlist?list=PLcx_iGeB-Nxil4S7-0Y1Y5r0oLahy3f0Y @lornajane

Slide 36

Slide 36

@lornajane