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)
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/
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/
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
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
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/
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
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
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)
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!
Documentation Driven Development > Write OpenAPI schema first > Call Jane to generate the API structure (& the client) > Code the business logic in the API