Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Introduction to OpenAPI Specification

Introduction to OpenAPI Specification

High level intro to OpenAPI spec aimed mostly at writers

Lorna Mitchell

November 09, 2018
Tweet

More Decks by Lorna Mitchell

Other Decks in Technology

Transcript

  1. Introduction to Open
    API Specification
    Lorna Mitchell, Nexmo

    View full-size slide

  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

    View full-size slide

  3. Spec-First API Design
    @lornajane

    View full-size slide

  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

    View full-size slide

  5. New APIs or Existing Ones?
    @lornajane

    View full-size slide

  6. New APIs or Existing Ones?
    Yes!
    @lornajane

    View full-size slide

  7. Who Writes OpenAPI Specs?
    @lornajane

    View full-size slide

  8. Anatomy of OpenAPI Spec
    @lornajane

    View full-size slide

  9. Anatomy of OpenAPI Spec
    Top-level elements:
    • openapi
    • info
    • servers
    • paths
    • components
    • security
    • tags
    @lornajane

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  14. That looks complicated!
    @lornajane

    View full-size slide

  15. Rendered Example: ReDoc
    @lornajane

    View full-size slide

  16. Rendered Example: Nexmo
    @lornajane

    View full-size slide

  17. Tools To Get Things Done
    @lornajane

    View full-size slide

  18. Please use Source Control
    See also: https://gitworkbook.com
    @lornajane

    View full-size slide

  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

    View full-size slide

  20. OAS in Atom
    @lornajane

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  23. Creating OpenAPI Specs is like
    eating an elephant
    @lornajane

    View full-size slide

  24. Uses for OpenAPI Spec
    @lornajane

    View full-size slide

  25. Resources
    • https://www.openapis.org
    • https://apievangelist.com
    • https://speccy.io
    • https://github.com/Rebilly/ReDoc
    • https://openapi.tools
    @lornajane

    View full-size slide