Spec First API Development With OpenAPI

Spec First API Development With OpenAPI

Imagine a world where the mobile development team is not constantly surprised by changing endpoints, where frontend developers don’t abuse your carefully crafted APIs and we don’t have to go back again and again to fix or change stuff. In this imaginary land we are able to leave the guesswork out by using API definitions to produce even better designs and automate parts of the process. Together we will explore OpenAPI as a standard way to describe APIs and see how it can help us get there.

807dcecdfca0e4078d89127cd440c039?s=128

Boyan Yordanov

June 15, 2019
Tweet

Transcript

  1. Spec First API Development With OpenAPI and Friends 1/98 —

    VarnaConf 2019 | @specter_bg
  2. So you need to build an API 2/98 — VarnaConf

    2019 | @specter_bg
  3. Where do you start? 3/98 — VarnaConf 2019 | @specter_bg

  4. The Database? 4/98 — VarnaConf 2019 | @specter_bg

  5. The Clients? 5/98 — VarnaConf 2019 | @specter_bg

  6. The Code? 6/98 — VarnaConf 2019 | @specter_bg

  7. What about docs? 7/98 — VarnaConf 2019 | @specter_bg

  8. What about tests? 8/98 — VarnaConf 2019 | @specter_bg

  9. What about validation? 9/98 — VarnaConf 2019 | @specter_bg

  10. And now you need to change something 10/98 — VarnaConf

    2019 | @specter_bg
  11. Sounds familiar? 11/98 — VarnaConf 2019 | @specter_bg

  12. GET /speakers/boyan → Boyan Yordanov → Ranting at @specter_bg →

    PHP Varna and VarnaJS organizer → VarnaLab member → Developer @ Shtrak 12/98 — VarnaConf 2019 | @specter_bg
  13. So who likes writing documentation? 13/98 — VarnaConf 2019 |

    @specter_bg
  14. Documentation that is: → "too long to read" → "totally

    useless" → "not updated" 14/98 — VarnaConf 2019 | @specter_bg
  15. just boring 15/98 — VarnaConf 2019 | @specter_bg

  16. API Specifications 16/98 — VarnaConf 2019 | @specter_bg

  17. → machine readable → easy to write → more than

    documentation 17/98 — VarnaConf 2019 | @specter_bg
  18. I still have to write it, though. — me 18/98

    — VarnaConf 2019 | @specter_bg
  19. I can do so much with it. — also me

    (a couple of months later) 19/98 — VarnaConf 2019 | @specter_bg
  20. So why bother with an API specification? 20/98 — VarnaConf

    2019 | @specter_bg
  21. → Endpoints change or disappear. → Your client is out

    of date. → Parameters switch types. → Tests fail. You have to go on a quest ... again. 1 1 http://www.commitstrip.com 21/98 — VarnaConf 2019 | @specter_bg
  22. 22/98 — VarnaConf 2019 | @specter_bg

  23. 23/98 — VarnaConf 2019 | @specter_bg

  24. Our process has failed us 24/98 — VarnaConf 2019 |

    @specter_bg
  25. 1. little upfront design work 25/98 — VarnaConf 2019 |

    @specter_bg
  26. 2. unannounced or miscommunicated changes 26/98 — VarnaConf 2019 |

    @specter_bg
  27. waste 27/98 — VarnaConf 2019 | @specter_bg

  28. frustration 28/98 — VarnaConf 2019 | @specter_bg

  29. more meetings 29/98 — VarnaConf 2019 | @specter_bg

  30. Common problems → changes aren't properly tested → clients constantly

    wait for the API → documentation and code don't match → SDKs have another opinion 30/98 — VarnaConf 2019 | @specter_bg
  31. https://blog.apisyouwonthate.com/why-do-people-dislike-json- a7d67c8d38c1 31/98 — VarnaConf 2019 | @specter_bg

  32. What can we do? 32/98 — VarnaConf 2019 | @specter_bg

  33. 33/98 — VarnaConf 2019 | @specter_bg

  34. Weeks of coding can save you hours of planning! —

    unknown 34/98 — VarnaConf 2019 | @specter_bg
  35. Specification first 35/98 — VarnaConf 2019 | @specter_bg

  36. Specifications as contracts 36/98 — VarnaConf 2019 | @specter_bg

  37. Game plan 37/98 — VarnaConf 2019 | @specter_bg

  38. 1. discuss the design 38/98 — VarnaConf 2019 | @specter_bg

  39. 2. write the specification 39/98 — VarnaConf 2019 | @specter_bg

  40. 3. generate docs and mock API 40/98 — VarnaConf 2019

    | @specter_bg
  41. 4. refine the specification 41/98 — VarnaConf 2019 | @specter_bg

  42. 5. use it in tests 42/98 — VarnaConf 2019 |

    @specter_bg
  43. 6. work on the code 43/98 — VarnaConf 2019 |

    @specter_bg
  44. Benefits 1. single source of truth for our design 2.

    always up to date documentation and tests 3. work on backend and clients independently 44/98 — VarnaConf 2019 | @specter_bg
  45. API Specification Formats 45/98 — VarnaConf 2019 | @specter_bg

  46. 46/98 — VarnaConf 2019 | @specter_bg

  47. API Blueprint → quite mature → markdown based → development

    is open on GitHub → mostly documentation oriented → tooling for the most essential things 47/98 — VarnaConf 2019 | @specter_bg
  48. RAML → yaml based → covers the whole design/development process

    → syntax is quite similar to the OpenAPI Specification 48/98 — VarnaConf 2019 | @specter_bg
  49. JSON Schema → json based → focused on the data

    model → great for validation and tests → has json-hyper-schema for hypermedia 49/98 — VarnaConf 2019 | @specter_bg
  50. 50/98 — VarnaConf 2019 | @specter_bg

  51. formerly known as Swagger 51/98 — VarnaConf 2019 | @specter_bg

  52. formerly known as Swagger 52/98 — VarnaConf 2019 | @specter_bg

  53. It's OpenAPI now 53/98 — VarnaConf 2019 | @specter_bg

  54. About the spec → has lots of tools → yaml

    or json based → very active community → backed by companies and widely adopted 54/98 — VarnaConf 2019 | @specter_bg
  55. OpenAPI Crash Course 55/98 — VarnaConf 2019 | @specter_bg

  56. read the spec at https://spec.openapis.org/oas/v3.0.2 56/98 — VarnaConf 2019 |

    @specter_bg
  57. Basic structure openapi: “3.0.0” info: # ... servers: # ...

    paths: # ... tags: # ... components: # ... 57/98 — VarnaConf 2019 | @specter_bg
  58. Basic information about the API info: description: >- *Imaginary* API

    for managing meetups. Imagined for this **VarnaConf 2019** talk. version: '0.1' title: Meetups Are Awesome API contact: email: boyan.yordanov.dev@gmail.com name: Boyan Yordanov url: 'https://boyanyordanov.com' license: # ... 58/98 — VarnaConf 2019 | @specter_bg
  59. How can users access the api servers: - url: 'https://imaginary-meetups.com/api'

    description: Imaginary API for managing Meetups - url: 'https://staging.imaginary-meetups.com/api' description: Staging server for the imaginary API - url: 'http://localhost:8080' description: Development version of the API 59/98 — VarnaConf 2019 | @specter_bg
  60. What can the API do paths: /meetups # ... /meetups/{id}

    # ... /meetups/{id}/events # ... 60/98 — VarnaConf 2019 | @specter_bg
  61. A path description /meetups: summary: meetups description: Meetups resource tags:

    # .. parameters: # .. get: # ... post: # .. 61/98 — VarnaConf 2019 | @specter_bg
  62. Describing parameters /meetups: # ... parameters: - name: city in:

    query / path / header description: Filter meetups based on city schema: type: string 62/98 — VarnaConf 2019 | @specter_bg
  63. handling array parameters /meetups: # ... parameters: - name: technologies

    in: query` description: Filter meetups based on city schema: type: array items: type: string style: form explode: false 63/98 — VarnaConf 2019 | @specter_bg
  64. Possible responses /meetups/{id} get: responses: '200': content: application/json: schema: #

    ... '404': content: application/problem+json: # ... 64/98 — VarnaConf 2019 | @specter_bg
  65. Schema objects → based JSON Schema draft 4 witch some

    things added and some taken out → support references → in future might support current versions of JSON Schema and other formats 65/98 — VarnaConf 2019 | @specter_bg
  66. example schema schema: type: object properties: id: type: string format:

    uuid name: type: string starting-date: type: string format: date 66/98 — VarnaConf 2019 | @specter_bg
  67. nullable fields city: description: either a string or null type:

    string nullable: true 67/98 — VarnaConf 2019 | @specter_bg
  68. other schema formats still a proposal 7 response: '200': content:

    application/json: x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json 7 https://github.com/stoplightio/spectral 68/98 — VarnaConf 2019 | @specter_bg
  69. Reference object → object with $ref property → reference objects

    in the same document → reference external documents → replace inline definitions for most OpenAPI components 69/98 — VarnaConf 2019 | @specter_bg
  70. Replace almost anything in the spec schema: $ref: '#/components/schemas/Meetup' #

    ... responses: '200': content: application/json: schema: $ref: 'MeetupsListResponse.yaml' 70/98 — VarnaConf 2019 | @specter_bg
  71. Components components: schemas: # ... responses: # ... parameters: #

    ... requestBodies: # ... headers: # ... examples: # ... 71/98 — VarnaConf 2019 | @specter_bg
  72. Tools 72/98 — VarnaConf 2019 | @specter_bg

  73. Editors 73/98 — VarnaConf 2019 | @specter_bg

  74. VSCode with openapi-lint extention → validates and lints → resloves

    external references → converts OpenAPI 2.0 to OpenAPI 3.0 → intellisense for both formats 74/98 — VarnaConf 2019 | @specter_bg
  75. Swagger Editor 75/98 — VarnaConf 2019 | @specter_bg

  76. Apicurio 76/98 — VarnaConf 2019 | @specter_bg

  77. OpenAPI GUI 77/98 — VarnaConf 2019 | @specter_bg

  78. Senya Editor 3 → PhpStorm (JetBrains) plugin → smart completion

    → live linting → handles $refs well → preview in Swagger UI ¯\_(ϑ)_/¯ → quite expensive 3 https://senya.io 78/98 — VarnaConf 2019 | @specter_bg
  79. Linters 79/98 — VarnaConf 2019 | @specter_bg

  80. Speccy 4 → lints your specification → supports rulesets →

    docs preview with ReDoc → resolve spec in one file → supports external references written in json- schema 4 https://github.com/wework/speccy 80/98 — VarnaConf 2019 | @specter_bg
  81. Spectral 7 → based entirely on rulesets → lints OpenAPI

    2/3 out of the box → extremely flexible 7 https://github.com/stoplightio/spectral 81/98 — VarnaConf 2019 | @specter_bg
  82. Documentation 82/98 — VarnaConf 2019 | @specter_bg

  83. Swagger UI - least favorite 83/98 — VarnaConf 2019 |

    @specter_bg
  84. Widdershins + Slate / Shins.js 84/98 — VarnaConf 2019 |

    @specter_bg
  85. ReDoc 85/98 — VarnaConf 2019 | @specter_bg

  86. Mock Servers 86/98 — VarnaConf 2019 | @specter_bg

  87. Stoplight.io / Prism 5 $ npm install -g @stoplight/prism-cli $

    prism mock openapi.yml APISprout 6 $ docker pull danielgtaylor/apisprout $ docker run -p 8000:8000 danielgtaylor/apisprout openapi.yaml 6 https://github.com/danielgtaylor/apisprout 5 https://github.com/stoplightio/prism 87/98 — VarnaConf 2019 | @specter_bg
  88. Testing 88/98 — VarnaConf 2019 | @specter_bg

  89. Postman → import trough the app → import using the

    API 89/98 — VarnaConf 2019 | @specter_bg
  90. OpenAPI <-> JSON Schema conversion https://github.com/mikunn/openapi2schema https://github.com/wework/json-schema-to- openapi-schema 90/98 —

    VarnaConf 2019 | @specter_bg
  91. Why convert? best of both worlds (sort of) 91/98 —

    VarnaConf 2019 | @specter_bg
  92. Example test 2 describe Api::MeetupsController, :type => :request do describe

    "GET /meetups" do it 'should return a list of meetups' do # ... get '/meetups' expect(response).to have_http_status(:success) expect(response).to match_json_schema("meetups") end end end 2 https://github.com/thoughtbot/json_matchers 92/98 — VarnaConf 2019 | @specter_bg
  93. Code Generation 93/98 — VarnaConf 2019 | @specter_bg

  94. OpenAPI Generator → community supported fork of swagger-codegen → supports

    OpenAPI 3.0 → Updated templates for different languages and frameworks 94/98 — VarnaConf 2019 | @specter_bg
  95. openapi.tools thanks to Phil Sturgeon and Matthew Trask 95/98 —

    VarnaConf 2019 | @specter_bg
  96. Thank you! 96/98 — VarnaConf 2019 | @specter_bg

  97. Questions? 97/98 — VarnaConf 2019 | @specter_bg

  98. Resources → Specification: https://swagger.io/specification → https://github.com/OAI/OpenAPI-Specification - issues / PRs

    → https://apisyouwonthate.com - books/blog/slack → https://philsturgeon.uk → https://apihandyman.io → https://apievangelist.com → http://json-schema.org → http://www.commitstrip.com/en/2018/02/26/its-good-to-have- experience/ 98/98 — VarnaConf 2019 | @specter_bg