Jane & Webby

Jane & Webby

Talk given at Forum PHP 2020

418997665c4a3368515ecf9c3d746b95?s=128

Olivier Dolbeau

October 23, 2020
Tweet

Transcript

  1. Jane & Webby BFFL

  2. Schedule 1. What is OAS? 2. OAS in action 3.

    Why OAS @Coverd? 4. OAS @Coverd
  3. What is OAS?

  4. OAS stands for OpenAPI Specification > The OpenAPI Specification: a

    broadly adopted industry standard for describing modern APIs. > 35+ members in the OpenAPI Initiative. (including Google, ebay, Microsoft, IBM, Atlassian, …) > Formerly Swagger (OpenAPI 2.0) > Current version: 3.0.3 (published 20 February 2020)
  5. This is a example A very simple one

  6. Basic information Version, license, ...

  7. A GET operation Everything you need to know to retrieve

    a list of pets!
  8. Here is our Pet (and our Pet collection)

  9. There is more! > Describe your security > Describe requests

    bodies > Describe your webhooks (NEW) > Add more context with the magic “x-” property https://api-platform.com/docs/distribution/
  10. OpenAPI in action You're going to meet my buddies

  11. Webby World famous OpenAPI writer

  12. APIP: API Platform > REST and GraphQL framework to build

    modern API-driven projects > Expose endpoints for a given entity really quickly > Browse documentation (spoiler: it uses OpenAPI) > Respects a lot of standards & interact very well with existing tools. https://api-platform.com/docs/distribution/
  13. Install APIP

  14. https://swagger.io/tools/swagger-ui/

  15. Jane Queen of PHP code generation

  16. None
  17. Jane Queen of PHP code generation

  18. None
  19. Jane: The AutoMapper > A library that generates AutoMapper class

    which allows to automap values from Class to Class. > Works like the symfony/serializer, without reflection at runtime (except the first run) https://jane.readthedocs.io/en/latest/components/AutoMapper.html
  20. Use case: Transform an entity to another object.

  21. Without Jane

  22. With Jane

  23. None
  24. Jane: API Client generation > Generate an API Client based

    on your OpenApi Schema. > Use the AutoMapper to map array (results from API) to POPO. https://jane.readthedocs.io/en/latest/documentation/OpenAPI.html
  25. None
  26. OpenAPI in action with APIP & Jane 1. Create your

    endpoints with API Platform 2. Export the associated OpenAPI schema 3. Use it to generate a PHP Client with Jane 4. Use it to generate a documentation page with Swagger UI (done in APIP) https://api-platform.com/docs/distribution/
  27. Why OpenAPI @Coverd?

  28. None
  29. Coverd next steps > From B2C only to B2C +

    B2B2C > Need to expose an API for our partners (with its documentation) > Create a new website dedicated to partners (stats, documentation, errors, dev tools, ...) > Good occasion to go API first & split our backoffice from our website
  30. OpenAPI @Coverd

  31. Which stack? > API Platform > Jane > Swagger UI

  32. Which stack? > API Platform => Homemade solution > Jane

    => ❤ Jane, Jane, JANE! ❤ > Swagger UI => Redoc
  33. ⚠ Disclaimer ⚠ API Platform is a very good solution!

  34. Homemade solution? Why & how we chose to replace APIP

  35. API Platform replacement: reason 1 > API Platform have a

    limited support of OpenAPI Specification > Some auto generated names > Hard to generate exactly the expected schema
  36. https://github.com/zircote/swagger-php

  37. API Platform replacement: reason 2 > API Platform is tight

    to an entity (or any object) > hard to define custom Input / Output for a given operation
  38. None
  39. Code tree Operations for a given endpoint

  40. Input POST /api_clients

  41. Output POST /api_clients

  42. Action The business code for POST /api_clients

  43. https://github.com/zircote/swagger-php

  44. None
  45. Custom code What we’ve done to achieve this

  46. ParamConverter To deserialize & validate inputs

  47. ParamConverter To inject object in actions (ie: GET /api_clients/{ID})

  48. jsonproblem RFC 7807 > 1 subscriber (Thanks APIP! ❤) >

    1 exception formatter > JSON output contains an URL > Error detail is available online > Declared errors are available through the API (GET /errors)
  49. Permissions > 1 endpoint = 1 voter > 1 action

    on this endpoint = 1 role in this voter
  50. And also... > Deal with collections > Permissions on properties

  51. Documentation Cause documentation matters (a lot)

  52. Documentation as a partner https://github.com/Redocly/redoc

  53. Internal documentation https://github.com/Redocly/redoc

  54. How to manage multiple documentations? DON’T!

  55. How to display different documentations? > Documentation is available through

    a dedicated domain > You MUST be identified to access documentation > The documentation is generated by the API according to you API credentials > We proxified the documentation!
  56. POST /api_clients

  57. None
  58. None
  59. Big picture Steps to follow to add a new endpoint

  60. GET /api_clients/{ID} Retrieve an Client from API

  61. SPOILER

  62. None
  63. Step 1: API How to add the new endpoint

  64. Output Informations returned by the API https://meta.stoplight.io/docs/prism/README.md

  65. Action Actually return the API Client

  66. OpenAPI Updating the documentation bin/console openapi:export

  67. Not shown Some code have not been presented > Voter

    update to add the new role > DataProvider which return an APIClient from an ID
  68. Step 2: API Client Updating the client used in applications

  69. Generate client Update existing generated code vendor/bin/jane-openapi generate

  70. None
  71. None
  72. None
  73. How to add a isDeleted() method? Customizing the generated client

  74. New Model Custom class which inherits the generated model.

  75. ApiClientStorage Wrap the generated client. Use Jane! ❤

  76. Step 3: Use it! Simply use the client in your

    app!
  77. Going further What I’d really like to achieve in a

    perfect world
  78. DDD Documentation Driven Development

  79. Documentation Driven Development > Write OpenAPI schema first > Call

    Jane to generate the API structure (& the client) > Code the business logic in the API
  80. None
  81. Thank you! ❤ Questions are welcome