Beyond Documentation With OpenAPI

Beyond Documentation With OpenAPI

Presented at Bulgaria Web Summit 2018

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

April 14, 2018
Tweet

Transcript

  1. BEYOND BEYOND DOCUMENTATION WITH DOCUMENTATION WITH OpenAPI OpenAPI 1

  2. GET /SPEAKERS/BOYAN GET /SPEAKERS/BOYAN Boyan Yordanov @specter_bg PHP Varna organizer

    VarnaLab member Developer@ShtrakBG 2
  3. WHO LIKES WRITING WHO LIKES WRITING DOCUMENTATION? DOCUMENTATION? 3

  4. DOCUMENTATION THAT IS: DOCUMENTATION THAT IS: "too long to read"

    "totally useless" "not updated" 4 . 1
  5. JUST BORING JUST BORING 4 . 2

  6. API SPECIFICATIONS API SPECIFICATIONS machine readable easy to write more

    than documentation 5
  7. - me I still have to write it, though. 6

  8. - also me (a couple of months later) I can

    do so many cool things with this definition. 7
  9. WHY BOTHER WITH AN WHY BOTHER WITH AN API SPECIFICATION?

    API SPECIFICATION? 8
  10. HAVE YOU BEEN THIS HAVE YOU BEEN THIS PERSON? PERSON?

    9
  11. HOW ABOUT THIS? HOW ABOUT THIS? 10

  12. OUR PROCESS HAS FAILED US OUR PROCESS HAS FAILED US

    11
  13. 1. LITTLE UPFRONT DESIGN WORK 12 . 1

  14. 2. UNANNOUNCED OR MISCOMMUNICATED CHANGES 12 . 2

  15. WASTED TIME WASTED TIME AND AND A LOT OF FRUSTRATION

    A LOT OF FRUSTRATION 13
  16. COMMON PROBLEMS COMMON PROBLEMS documentation and code don't match SDKs

    have a third opinion changes aren't properly tested clients constantly wait for the API 14
  17. https://blog.apisyouwonthate.com/why-do-people-dislike- json-a7d67c8d38c1 15

  18. 16

  19. WHAT CAN WE DO? WHAT CAN WE DO? 17

  20. SPECIFICATION FIRST SPECIFICATION FIRST Nothing gets implemented until the API

    is defined 18
  21. SPECIFICATIONS AS CONTRACTS SPECIFICATIONS AS CONTRACTS verify that the API

    does what it says 19
  22. 20

  23. GAME PLAN GAME PLAN 1. produce the API specification 2.

    generate docs and mock API 3. refine the specification 4. use it in integration tests 5. work on the actual server code 21
  24. POTENTIAL BENEFITS POTENTIAL BENEFITS 22 . 1

  25. 1. EVERYTHING NEW EVERYTHING NEW HAPPENS FIRST IN THE HAPPENS

    FIRST IN THE SPEC SPEC 22 . 2
  26. 2. ALWAYS UP TO DATE ALWAYS UP TO DATE DOCUMENTATION

    AND DOCUMENTATION AND TESTS TESTS 22 . 3
  27. 3. BACKEND AND BACKEND AND CLIENTS CLIENTS CAN BE DEVELOPED

    CAN BE DEVELOPED INDEPENDENTLY INDEPENDENTLY 22 . 4
  28. API SPECIFICATION FORMATS API SPECIFICATION FORMATS 23

  29. API BLUEPRINT API BLUEPRINT markdown based development is open on

    GitHub it's quite mature there's tooling for the most essential things mostly documentation oriented 24
  30. RAML - RESTFUL API MODELING RAML - RESTFUL API MODELING

    LANGUAGE LANGUAGE yaml based syntax is quite similar to the OpenAPI Specification covers the whole design/development process 25
  31. JSON SCHEMA JSON SCHEMA not entirely fair to include it

    here json based focused only on the data model great for validation and tests includes syntax for describing hypermedia controls 26
  32. 27

  33. formerly known as Swagger yaml or json based very actively

    developed very active community 28
  34. HOW TO WRITE AN HOW TO WRITE AN OPENAPI OPENAPI

    SPECIFICATION SPECIFICATION 29
  35. BASIC STRUCTURE BASIC STRUCTURE openapi: “3.0.0” info: # ... servers:

    # ... paths: # ... tags: # ... components: # ... 30
  36. Let's build a simple OpenAPI Let's build a simple OpenAPI

    speci cation speci cation 31
  37. BASIC INFORMATION ABOUT THE API BASIC INFORMATION ABOUT THE API

    info: description: >- *Imaginary* API for managing meetups. Imagined for this **BWS 2018** talk. version: '0.1' title: Meetups Are Awesome API contact: email: boyan.yordanov.dev@gmail.com name: Boyan Yordanov url: 'https://boyanyordanov.com' license: # ... 32
  38. HOW CAN USERS ACCESS THE API 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 33
  39. it also supports templating servers: - url: https://{username}.api-server.com/api/ description: User

    specific URLs variables: username: default: demo description: assigned upon registration 34
  40. WHAT CAN THE API DO WHAT CAN THE API DO

    35 . 1
  41. Just a list of paths and the possible requests and

    responses paths: /meetups # ... /meetups/{id} # ... /meetups/{id}/events # ... 35 . 2
  42. A path description /meetups: summary: meetups description: Meetups resource tags:

    # .. parameters: # .. get: # ... post: # .. 36
  43. 37

  44. DESCRIBING PARAMETERS DESCRIBING PARAMETERS /meetups: # ... parameters: - name:

    city in: query description: Filter meetups based on city schema: type: string 38
  45. POSSIBLE RESPONSES POSSIBLE RESPONSES /meetups/{id} get: responses: '200': content: application/json:

    schema: # ... '404': content: application/problem+json: # ... 39
  46. SCHEMA OBJECTS SCHEMA OBJECTS extended subset of JSON Schema draft

    5 support references in future might support current drafts of JSON Schema or other formats 40 . 1
  47. example schema schema: type: object properties: id: type: string format:

    uuid name: type: string starting-date: type: string format: date 40 . 2
  48. nullable fields city: description: either a string or null type:

    string nullable: true 40 . 3
  49. Reference object object with $ref property reference objects in the

    same document reference external documents replace inline definitions for most OpenAPI components 40 . 4
  50. Replace almost anything in the spec schema: $ref: '#/components/schemas/Meetup' #

    ... responses: '200': $ref: 'MeetupsListResponse.yaml' 40 . 5
  51. COMPONENTS COMPONENTS components: schemas: # ... responses: # ... parameters:

    # ... requestBodies: # ... headers: # ... examples: # 41
  52. We have an We have an OpenAPI Speci cation OpenAPI

    Speci cation What do we do with it? What do we do with it? 42
  53. EASY PICKINGS EASY PICKINGS HTML DOCUMENTATION HTML DOCUMENTATION 43 .

    1
  54. Swagger UI - least favorite 43 . 2

  55. Widdershins + Slate / Shins.js 43 . 3

  56. ReDoc - seems to be best 43 . 4

  57. LINTER - SPECCY LINTER - SPECCY https://github.com/wework/speccy lints your specification

    supports rulesets docs preview with ReDoc resolve spec in one file 44
  58. EDITORS EDITORS everything supporting yaml 45 . 1

  59. Swagger Editor 45 . 2

  60. Apicurio 45 . 3

  61. OpenAPI GUI - personal favorite 45 . 4

  62. CODE GENERATION CODE GENERATION SWAGGER-CODEGEN SWAGGER-CODEGEN (support for 3.0 is

    still in progress) 46 . 1
  63. generate server scaffolds generate clients / SDKs converting back to

    2.0 sort of works some templates might be out of date 46 . 2
  64. MOCK SERVERS MOCK SERVERS Supporting OpenAPI 3.0 only SwaggerHub at

    the moment 47
  65. POSTMAN COLLECTIONS POSTMAN COLLECTIONS Apimatic.io upload/download or use API transform

    to and from OpenAPI lots of formats including Postman 2.0 Collections 48 . 1
  66. OPENAPI / JSON SCHEMA OPENAPI / JSON SCHEMA CONVERSION CONVERSION

    https://github.com/mikunn/openapi2schema https://github.com/wework/json-schema-to- openapi-schema 49
  67. WHY CONVERT? WHY CONVERT? BEST OF BOTH WORLDS BEST OF

    BOTH WORLDS (sort of) 50
  68. EXAMPLE TEST EXAMPLE TEST https://github.com/thephpleague/json-guard // ... $schemas = json_decode(

    file_get_contents('meetups-schema.json') ); $response = $client->get('/api/meetups') $validator = new League\JsonGuard\Validator( json_decode($response->response->content()), $schema); $this->assertTrue($validator->passes()); 51
  69. MOAR TOOLS MOAR TOOLS thanks Phil Sturgeon and Matthew Trask

    OPENAPI.TOOLS OPENAPI.TOOLS 52
  70. THANK YOU! THANK YOU! QUESTIONS? QUESTIONS? 53

  71. RESOURCES RESOURCES Specification: - issues / PRs - books/blog/slack https://swagger.io/specification

    https://github.com/OAI/OpenAPI-Specification https://apisyouwonthate.com 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/ 54