Introduction to OpenAPI Specification

High level intro to OpenAPI spec aimed mostly at writers

Transcript

1. Introduction to Open API Specification Lorna Mitchell, Nexmo
2. Describing APIs • Describe RESTful HTTP APIs in a machine-readable way • API description is independent of outputs such as documentation • Enable things that are not "just" documentation @lornajane
3. Spec-First API Design @lornajane
4. About OpenAPI Spec API description language formerly known as "Swagger". Became "OpenAPI Spec" -> v3 released (some tools are still catching up on v3) @lornajane
5. New APIs or Existing Ones? @lornajane
6. New APIs or Existing Ones? Yes! @lornajane
7. Who Writes OpenAPI Specs? @lornajane
8. Anatomy of OpenAPI Spec @lornajane
9. Anatomy of OpenAPI Spec Top-level elements: • openapi • info • servers • paths • components • security • tags @lornajane
10. OpenAPI Spec Examples A JSON or YAML file holds the description (this is YAML) openapi: 3.0.0 servers: - url: 'https://api.nexmo.com' info: version: 1.0.0 title: Secret Management API ... a few hundred more lines here @lornajane
11. Documenting an Endpoint paths: /accounts/{account_id}/secrets: get: summary: Retrieve API Secrets operationId: retrieveSecrets parameters: - $ref: '#/components/parameters/accountId' responses: '200': ... '401': $ref: '#/components/responses/BadCredentialsError' '404': $ref: '#/components/responses/NotFoundError' @lornajane
12. Example 200 Response description: API secret response content: application/json: schema: properties: secrets: type: object description: A list of secrets under the "secrets" key. properties: secrets: type: array items: $ref: '#/components/schemas/SecretInfo' @lornajane
13. SecretInfo Reference schemas: SecretInfo: type: object properties: id: type: string description: Secret ID example: ad6dc56f-07b5-46e1-a527-85530e625800 created_at: type: string description: The date/time the secret was created example: '2017-03-02T16:34:49Z' @lornajane
14. That looks complicated! @lornajane
15. Rendered Example: ReDoc @lornajane
16. Rendered Example: Nexmo @lornajane
17. Tools To Get Things Done @lornajane
18. Please use Source Control See also: https://gitworkbook.com @lornajane
19. Editing Tools There are editors with helpful tools • I like Atom with linter-swagger https://atom.io • Try SwaggerUI, SwaggerHub, etc https://swagger.io/tools/ • APICurio Studio gets good reviews https://www.apicur.io/ • Stoplight looks interesting https://stoplight.io (feel free to tweet your best tools at me, I'll share them all later) @lornajane
20. OAS in Atom @lornajane
21. Validation Tools Tools that check or "lint" your file. • Speccy is a CLI tool with configurable rules http://speccy.io/ • Open API Spec Validator https://github.com/p1c2u/openapi-spec-validator Set up in your editor or use a watch command, e.g.: watch -n 1 speccy lint myspec.yml @lornajane
22. Preview Tools OAS is a standard! So any preview should do: • ReDoc is great https://github.com/Rebilly/ReDoc • Speccy also wraps ReDoc for its serve command • You can run OpenApi-GUI locally https://github.com/mermade/openapi-gui @lornajane
23. Creating OpenAPI Specs is like eating an elephant @lornajane
24. Uses for OpenAPI Spec @lornajane
25. Resources • https://www.openapis.org • https://apievangelist.com • https://speccy.io • https://github.com/Rebilly/ReDoc • https://openapi.tools @lornajane