Jane & Webby

Talk given at Forum PHP 2020

Transcript

1. Jane & Webby
   BFFL
   

   View Slide

2. Schedule
   1. What is OAS?
   2. OAS in action
   3. Why OAS @Coverd?
   4. OAS @Coverd
   

   View Slide

3. What is OAS?
   

   View Slide

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)
   

   View Slide

5. This is a
   example
   A very simple one
   

   View Slide

6. Basic
   information
   Version, license, ...
   

   View Slide

7. A GET operation
   Everything you need to know to
   retrieve a list of pets!
   

   View Slide

8. Here is our Pet
   (and our Pet collection)
   

   View Slide

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/
   

   View Slide

10. OpenAPI in action
    You're going to meet my buddies
    

    View Slide

11. Webby
    World famous OpenAPI writer
    

    View Slide

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/
    

    View Slide

13. Install APIP
    

    View Slide

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

    View Slide

15. Jane
    Queen of PHP code generation
    

    View Slide

16. View Slide

17. Jane
    Queen of PHP code generation
    

    View Slide

18. View Slide

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
    

    View Slide

20. Use case:
    Transform an
    entity to another
    object.
    

    View Slide

21. Without
    Jane
    

    View Slide

22. With
    Jane
    

    View Slide

23. View Slide

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
    

    View Slide

25. View Slide

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/
    

    View Slide

27. Why OpenAPI @Coverd?
    

    View Slide

28. View Slide

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
    

    View Slide

30. OpenAPI @Coverd
    

    View Slide

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

    View Slide

32. Which stack?
    > API Platform => Homemade solution
    > Jane => ❤ Jane, Jane, JANE! ❤
    > Swagger UI => Redoc
    

    View Slide

33. ⚠ Disclaimer ⚠
    API Platform is a very good solution!
    

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

38. View Slide

39. Code tree
    Operations for a given endpoint
    

    View Slide

40. Input
    POST /api_clients
    

    View Slide

41. Output
    POST /api_clients
    

    View Slide

42. Action
    The business code for
    POST /api_clients
    

    View Slide

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

    View Slide

44. View Slide

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

    View Slide

46. ParamConverter
    To deserialize & validate inputs
    

    View Slide

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

    View Slide

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)
    

    View Slide

49. Permissions > 1 endpoint = 1 voter
    > 1 action on this endpoint = 1 role
    in this voter
    

    View Slide

50. And also... > Deal with collections
    > Permissions on properties
    

    View Slide

51. Documentation
    Cause documentation matters (a lot)
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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!
    

    View Slide

56. POST /api_clients
    

    View Slide

57. View Slide

58. View Slide

59. Big picture
    Steps to follow to add a new endpoint
    

    View Slide

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

    View Slide

61. SPOILER
    

    View Slide

62. View Slide

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

    View Slide

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

    View Slide

65. Action
    Actually return the API Client
    

    View Slide

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

    View Slide

67. Not shown
    Some code have not been
    presented
    > Voter update to add the new role
    > DataProvider which return an
    APIClient from an ID
    

    View Slide

68. Step 2: API Client
    Updating the client used in
    applications
    

    View Slide

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

    View Slide

70. View Slide

71. View Slide

72. View Slide

73. How to add a
    isDeleted() method?
    Customizing the generated client
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

77. Going further
    What I’d really like to achieve in a
    perfect world
    

    View Slide

78. DDD
    Documentation Driven Development
    

    View Slide

79. Documentation Driven Development
    > Write OpenAPI schema first
    > Call Jane to generate the API structure (& the client)
    > Code the business logic in the API
    

    View Slide

80. View Slide

81. Thank you! ❤
    Questions are welcome
    

    View Slide