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.

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