Introduction to OpenAPI Specification

High level intro to OpenAPI spec aimed mostly at writers

Transcript

1. Introduction to Open
   API Specification
   Lorna Mitchell, Nexmo
   

   View 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 Slide

3. Spec-First API Design
   @lornajane
   

   View 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 Slide

5. New APIs or Existing Ones?
   @lornajane
   

   View Slide

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

   View Slide

7. Who Writes OpenAPI Specs?
   @lornajane
   

   View Slide

8. Anatomy of OpenAPI Spec
   @lornajane
   

   View Slide

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

   View 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 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 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 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 Slide

14. That looks complicated!
    @lornajane
    

    View Slide

15. Rendered Example: ReDoc
    @lornajane
    

    View Slide

16. Rendered Example: Nexmo
    @lornajane
    

    View Slide

17. Tools To Get Things Done
    @lornajane
    

    View Slide

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

    View 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 Slide

20. OAS in Atom
    @lornajane
    

    View 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 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 Slide

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

    View Slide

24. Uses for OpenAPI Spec
    @lornajane
    

    View Slide

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

    View Slide