Introduction to OpenAPI Specification

Introduction to OpenAPI Specification

High level intro to OpenAPI spec aimed mostly at writers

D33d8bdd9096c80b8d1acca8d28410b5?s=128

Lorna Mitchell

November 09, 2018
Tweet

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