OpenAPI 3.0.0-RC0 APICraft SF Meetup

Transcript

1. The OpenAPI Specification 3.0 … the next generation Ron Ratovsky, @webron SmartBear March 9, 2017
2. CommonMark in, GFM out GFM
3. Structural Improvements OpenAPI 2.0 info host paths parameters security tags externalDocs basePath schemes securityDefinitions responses definitions produces consumes OpenAPI 3.0 info servers paths components security tags externalDocs
4. Introducing Servers • Replaces schemes, host, basePath • Allows definition of multiple servers • Variable substitution support • Defined at top, path or operation level servers: - url: https://{user}.big- server.com:{port}/{path} description: The production API server variables: user: default: demo port: enum: - 8443 - 443 default: 8443 path: default: v2
5. Extended Reusability • All under one roof • Standardized naming • Added new objects OpenAPI 3.0 Components schemas responses parameters examples requestBodies headers securitySchemes links callbacks
6. Path Item Changes • Description • New TRACE support • Override Servers • No support for payloads for GET, DELETE…
7. Parameters Overview
8. Request Body & Content • Specify different Media Types • Supports reusability • Provide examples • Replaces formData parameters • Improved file upload handling
9. Parameters Parameter name in description required deprecated allowEmptyValue style explode allowReserved schema example examples content
10. Responses • Wildcard response codes • Response headers can be complex types too • Content for payload • Introducing: Links
11. Links
12. Callbacks myWebhook: '$request.body#/url': post: requestBody: description: Callback payload content: 'application/json’: schema: $ref: '#/components/schemas/SomePayload' responses: 200: description: webhook successfully processed an no retries will be performed
13. JSON Schema • Updated support to latest Wright Draft 00 (Draft 05) • Added support for onyOf, anyOf, not • nullable, deprecated, writeOnly • Clarified JSON References • Clarified other restrictions
14. Security Definitions • OAuth2 flow names finally make sense • Multiple flow support • Introduced support for OpenID Connect • Replaced `basic` with `http` and… • Added `scheme` and `bearerFormat`
15. Get Involved! Follow @OpenApiSpec Blog series on spec changes: bit.ly/openapi3changes OAI Website: openapis.org On GitHub (see the OpenAPI.Next branch): https://github.com/OAI