Beyond Documentation With OpenAPI

Slide 1

Slide 1 text

BEYOND BEYOND DOCUMENTATION WITH DOCUMENTATION WITH OpenAPI OpenAPI 1

Slide 2

Slide 2 text

GET /SPEAKERS/BOYAN GET /SPEAKERS/BOYAN Boyan Yordanov @specter_bg PHP Varna organizer VarnaLab member Developer@ShtrakBG 2

Slide 3

Slide 3 text

WHO LIKES WRITING WHO LIKES WRITING DOCUMENTATION? DOCUMENTATION? 3

Slide 4

Slide 4 text

DOCUMENTATION THAT IS: DOCUMENTATION THAT IS: "too long to read" "totally useless" "not updated" 4 . 1

Slide 5

Slide 5 text

JUST BORING JUST BORING 4 . 2

Slide 6

Slide 6 text

API SPECIFICATIONS API SPECIFICATIONS machine readable easy to write more than documentation 5

Slide 7

Slide 7 text

- me I still have to write it, though. 6

Slide 8

Slide 8 text

- also me (a couple of months later) I can do so many cool things with this definition. 7

Slide 9

Slide 9 text

WHY BOTHER WITH AN WHY BOTHER WITH AN API SPECIFICATION? API SPECIFICATION? 8

Slide 10

Slide 10 text

HAVE YOU BEEN THIS HAVE YOU BEEN THIS PERSON? PERSON? 9

Slide 11

Slide 11 text

HOW ABOUT THIS? HOW ABOUT THIS? 10

Slide 12

Slide 12 text

OUR PROCESS HAS FAILED US OUR PROCESS HAS FAILED US 11

Slide 13

Slide 13 text

1. LITTLE UPFRONT DESIGN WORK 12 . 1

Slide 14

Slide 14 text

2. UNANNOUNCED OR MISCOMMUNICATED CHANGES 12 . 2

Slide 15

Slide 15 text

WASTED TIME WASTED TIME AND AND A LOT OF FRUSTRATION A LOT OF FRUSTRATION 13

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

https://blog.apisyouwonthate.com/why-do-people-dislike- json-a7d67c8d38c1 15

Slide 18

Slide 18 text

Slide 19

Slide 19 text

WHAT CAN WE DO? WHAT CAN WE DO? 17

Slide 20

Slide 20 text

SPECIFICATION FIRST SPECIFICATION FIRST Nothing gets implemented until the API is defined 18

Slide 21

Slide 21 text

SPECIFICATIONS AS CONTRACTS SPECIFICATIONS AS CONTRACTS verify that the API does what it says 19

Slide 22

Slide 22 text

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

POTENTIAL BENEFITS POTENTIAL BENEFITS 22 . 1

Slide 25

Slide 25 text

1. EVERYTHING NEW EVERYTHING NEW HAPPENS FIRST IN THE HAPPENS FIRST IN THE SPEC SPEC 22 . 2

Slide 26

Slide 26 text

2. ALWAYS UP TO DATE ALWAYS UP TO DATE DOCUMENTATION AND DOCUMENTATION AND TESTS TESTS 22 . 3

Slide 27

Slide 27 text

3. BACKEND AND BACKEND AND CLIENTS CLIENTS CAN BE DEVELOPED CAN BE DEVELOPED INDEPENDENTLY INDEPENDENTLY 22 . 4

Slide 28

Slide 28 text

API SPECIFICATION FORMATS API SPECIFICATION FORMATS 23

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

Slide 33

Slide 33 text

formerly known as Swagger yaml or json based very actively developed very active community 28

Slide 34

Slide 34 text

HOW TO WRITE AN HOW TO WRITE AN OPENAPI OPENAPI SPECIFICATION SPECIFICATION 29

Slide 35

Slide 35 text

BASIC STRUCTURE BASIC STRUCTURE openapi: “3.0.0” info: # ... servers: # ... paths: # ... tags: # ... components: # ... 30

Slide 36

Slide 36 text

Let's build a simple OpenAPI Let's build a simple OpenAPI speci cation speci cation 31

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

WHAT CAN THE API DO WHAT CAN THE API DO 35 . 1

Slide 41

Slide 41 text

Just a list of paths and the possible requests and responses paths: /meetups # ... /meetups/{id} # ... /meetups/{id}/events # ... 35 . 2

Slide 42

Slide 42 text

A path description /meetups: summary: meetups description: Meetups resource tags: # .. parameters: # .. get: # ... post: # .. 36

Slide 43

Slide 43 text

Slide 44

Slide 44 text

DESCRIBING PARAMETERS DESCRIBING PARAMETERS /meetups: # ... parameters: - name: city in: query description: Filter meetups based on city schema: type: string 38

Slide 45

Slide 45 text

POSSIBLE RESPONSES POSSIBLE RESPONSES /meetups/{id} get: responses: '200': content: application/json: schema: # ... '404': content: application/problem+json: # ... 39

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

example schema schema: type: object properties: id: type: string format: uuid name: type: string starting-date: type: string format: date 40 . 2

Slide 48

Slide 48 text

nullable fields city: description: either a string or null type: string nullable: true 40 . 3

Slide 49

Slide 49 text

Reference object object with $ref property reference objects in the same document reference external documents replace inline definitions for most OpenAPI components 40 . 4

Slide 50

Slide 50 text

Replace almost anything in the spec schema: $ref: '#/components/schemas/Meetup' # ... responses: '200': $ref: 'MeetupsListResponse.yaml' 40 . 5

Slide 51

Slide 51 text

COMPONENTS COMPONENTS components: schemas: # ... responses: # ... parameters: # ... requestBodies: # ... headers: # ... examples: # 41

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

EASY PICKINGS EASY PICKINGS HTML DOCUMENTATION HTML DOCUMENTATION 43 . 1

Slide 54

Slide 54 text

Swagger UI - least favorite 43 . 2

Slide 55

Slide 55 text

Widdershins + Slate / Shins.js 43 . 3

Slide 56

Slide 56 text

ReDoc - seems to be best 43 . 4

Slide 57

Slide 57 text

LINTER - SPECCY LINTER - SPECCY https://github.com/wework/speccy lints your specification supports rulesets docs preview with ReDoc resolve spec in one file 44

Slide 58

Slide 58 text

EDITORS EDITORS everything supporting yaml 45 . 1

Slide 59

Slide 59 text

Swagger Editor 45 . 2

Slide 60

Slide 60 text

Apicurio 45 . 3

Slide 61

Slide 61 text

OpenAPI GUI - personal favorite 45 . 4

Slide 62

Slide 62 text

CODE GENERATION CODE GENERATION SWAGGER-CODEGEN SWAGGER-CODEGEN (support for 3.0 is still in progress) 46 . 1

Slide 63

Slide 63 text

generate server scaffolds generate clients / SDKs converting back to 2.0 sort of works some templates might be out of date 46 . 2

Slide 64

Slide 64 text

MOCK SERVERS MOCK SERVERS Supporting OpenAPI 3.0 only SwaggerHub at the moment 47

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

OPENAPI / JSON SCHEMA OPENAPI / JSON SCHEMA CONVERSION CONVERSION https://github.com/mikunn/openapi2schema https://github.com/wework/json-schema-to- openapi-schema 49

Slide 67

Slide 67 text

WHY CONVERT? WHY CONVERT? BEST OF BOTH WORLDS BEST OF BOTH WORLDS (sort of) 50

Slide 68

Slide 68 text

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

Slide 69

Slide 69 text

MOAR TOOLS MOAR TOOLS thanks Phil Sturgeon and Matthew Trask OPENAPI.TOOLS OPENAPI.TOOLS 52

Slide 70

Slide 70 text

THANK YOU! THANK YOU! QUESTIONS? QUESTIONS? 53

Slide 71

Slide 71 text

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