Beyond Documentation with OpenAPI (PHP Central Europe 2018)

Beyond Documentation with OpenAPI (PHP Central Europe 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.


Boyan Yordanov

October 28, 2018


  1. 8.

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

    do so many cool things with this de nition.
  2. 16.

    COMMON PROBLEMS changes aren't properly tested clients constantly wait for

    the API documentation and code don't match SDKs have another opinion
  3. 18.
  4. 22.
  5. 23.

    GAME PLAN 1. produce the API speci cation 2. generate

    docs and mock API 3. re ne the speci cation 4. use it in integration tests 5. work on the actual server code
  6. 29.
  7. 30.

    API BLUEPRINT markdown based development is open on GitHub it's

    quite mature there's tooling for the most essential things mostly documentation oriented
  8. 31.

    RAML RESTful API Modeling Language yaml based syntax is quite

    similar to the OpenAPI Speci cation covers the whole design/development process
  9. 32.

    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
  10. 33.
  11. 34.

    formerly known as Swagger don't call it that please yaml

    or json based very actively developed very active community
  12. 36.

    BASIC STRUCTURE openapi: “3.0.0” info: # ... servers: # ...

    paths: # ... tags: # ... components: # ...
  13. 38.

    BASIC INFORMATION ABOUT THE API info: description: >­ *Imaginary* API

    for managing meetups. Imagined for this **PHPCE 2018** talk. version: '0.1' title: Meetups Are Awesome API contact: email: name: Boyan Yordanov url: '' license: # ...
  14. 39.

    HOW CAN USERS ACCESS THE API servers: ­ url: 'https://imaginary­'

    description: Imaginary API for managing Meetups ­ url: 'https://staging.imaginary­' description: Staging server for the imaginary AP ­ url: 'http://localhost:8080' description: Development version of the API
  15. 40.

    it also supports templating servers: ­ url: https://{username}.api­ description: User

    specific URLs variables: username: default: demo description: assigned upon registration
  16. 42.

    Just a list of paths and the possible requests and

    responses paths: /meetups # ... /meetups/{id} # ... /meetups/{id}/events # ...
  17. 44.
  18. 45.

    DESCRIBING PARAMETERS /meetups: # ... parameters: ­ name: city in:

    query / path / header description: Filter meetups based on city schema: type: string
  19. 46.

    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
  20. 49.

    SCHEMA OBJECTS "extended subset" of JSON Schema draft 5 support

    references in future will support current drafts of JSON Schema and other formats
  21. 50.

    example schema schema: type: object properties: id: type: string format:

    uuid name: type: string starting­date: type: string format: date
  22. 52.

    other schema formats still a proposal schema: x­oas­draft­alternativeSchema: type: jsonSchema

    location: ./real­jsonschema.json cation/issues/1532
  23. 53.

    REFERENCE OBJECT object with $ref property reference objects in the

    same document reference external documents replace inline de nitions for most OpenAPI components
  24. 54.

    Replace almost anything in the spec schema: $ref: '#/components/schemas/Meetup' #

    ... responses: '200': $ref: 'MeetupsListResponse.yaml'
  25. 55.

    COMPONENTS components: schemas: # ... responses: # ... parameters: #

    ... requestBodies: # ... headers: # ... examples: #
  26. 60.
  27. 61.

    LINTER - SPECCY lints your speci cation supports rulesets

    docs preview with ReDoc resolve spec in one le supports external references written in json-schema
  28. 65.
  29. 67.

    SENYA EDITOR PhpStorm (JetBrains) plugin free for the time

    being smart completion live linting handles $refs well preview in Swagger UI ¯\_( ツ)_/¯
  30. 70.

    JANE-PHP/JANE-PHP generates PSR-7 compatible SDKs can use different clients based

    on HTTPlug supports json-schema and OpenAPI OpenAPI v3 support was added recently
  31. 72.

    POSTMAN COLLECTIONS upload/download or use API transform to and

    from OpenAPI lots of formats including Postman 2.0 Collections
  32. 75.

    EXAMPLE TEST /** @test */ public function it_tests_with_swaggest_json_schema() {

    $schema = $this­>loadSchema('events'); $response = $this­>get('/events'); $this­>assertValidResponse($schema, $response); }
  33. 76.

    EXAMPLE ASSERTION protected function assertValidResponse( $schema, $response ){ $validator

    = Schema::import($schema); try { $data = json_decode($response­>getContent()); $validator­>in($data); $this­>assertTrue(true, 'Something went wrong.') } catch (InvalidValue $e) { $this­>fail($e­>getMessage()); } }
  34. 77.

    WORKING WITH THE SPECIFICATION Parse OpenAPI speci cation Generate from

    code Nice PHP API to work with the spec Supports other speci cations as well
  35. 78.

    PROOF OF CONCEPT TIME class ApiTest extends TestCase {

    use OpenAPITestTools\OpenAPIAssertions; /** @dataProvider getApiTestCases */ public function test_it_runs_openapi_based_tests( $path, $resource ) { $this­>assertValidContract($path, $resource); }
  36. 79.

    //... public function getApiTestCases(): array { $provider = new OpenAPITestTools\SpecDataProvide

    __DIR__ . '/../../openapi.yaml' ); return $provider­>getTestCases(); } }
  37. 82.

    RESOURCES Speci cation: - issues / PRs - books/blog/slack

    cation cation experience/