Jane & Webby

Talk given at Forum PHP 2020

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
17. Jane Queen of PHP code generation
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
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
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?
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
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
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
59. Big picture Steps to follow to add a new endpoint
60. GET /api_clients/{ID} Retrieve an Client from API
61. SPOILER
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
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
81. Thank you! ❤ Questions are welcome