$30 off During Our Annual Pro Sale. View details »

Introduction to OpenAPI Specification

Introduction to OpenAPI Specification

High level intro to OpenAPI spec aimed mostly at writers

Lorna Mitchell

November 09, 2018

More Decks by Lorna Mitchell

Other Decks in Technology


  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