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

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.

Boyan Yordanov

June 15, 2019
Tweet

More Decks by Boyan Yordanov

Other Decks in Technology

Transcript

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

    PHP Varna and VarnaJS organizer → VarnaLab member → Developer @ Shtrak 12/98 — VarnaConf 2019 | @specter_bg
  2. Documentation that is: → "too long to read" → "totally

    useless" → "not updated" 14/98 — VarnaConf 2019 | @specter_bg
  3. → machine readable → easy to write → more than

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

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

    (a couple of months later) 19/98 — VarnaConf 2019 | @specter_bg
  6. → 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
  7. 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
  8. Weeks of coding can save you hours of planning! —

    unknown 34/98 — VarnaConf 2019 | @specter_bg
  9. 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
  10. 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
  11. RAML → yaml based → covers the whole design/development process

    → syntax is quite similar to the OpenAPI Specification 48/98 — VarnaConf 2019 | @specter_bg
  12. 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
  13. 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
  14. Basic structure openapi: “3.0.0” info: # ... servers: # ...

    paths: # ... tags: # ... components: # ... 57/98 — VarnaConf 2019 | @specter_bg
  15. 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: [email protected] name: Boyan Yordanov url: 'https://boyanyordanov.com' license: # ... 58/98 — VarnaConf 2019 | @specter_bg
  16. 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
  17. What can the API do paths: /meetups # ... /meetups/{id}

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

    # .. parameters: # .. get: # ... post: # .. 61/98 — VarnaConf 2019 | @specter_bg
  19. 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
  20. 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
  21. Possible responses /meetups/{id} get: responses: '200': content: application/json: schema: #

    ... '404': content: application/problem+json: # ... 64/98 — VarnaConf 2019 | @specter_bg
  22. 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
  23. 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
  24. nullable fields city: description: either a string or null type:

    string nullable: true 67/98 — VarnaConf 2019 | @specter_bg
  25. 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
  26. 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
  27. 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
  28. Components components: schemas: # ... responses: # ... parameters: #

    ... requestBodies: # ... headers: # ... examples: # ... 71/98 — VarnaConf 2019 | @specter_bg
  29. 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
  30. 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
  31. 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
  32. 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
  33. 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
  34. Postman → import trough the app → import using the

    API 89/98 — VarnaConf 2019 | @specter_bg
  35. 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
  36. 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
  37. 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