Beyond Documentation With OpenAPI

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: [email protected] 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