$30 off During Our Annual Pro Sale. View Details »

Jane & Webby

Jane & Webby

Talk given at Forum PHP 2020

Olivier Dolbeau

October 23, 2020
Tweet

More Decks by Olivier Dolbeau

Other Decks in Technology

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