wp-calypso
wp-calypso copied to clipboard
Automattic
Marketplace: Product Licensing - Create an openapi like documentation
What
In order that Vendors adapt our licensing system it would be valuable for them to have a documentation / playground where they can:
- Understand what APIs are available and how to use them eg https://github.com/Automattic/wp-calypso/issues/65347
- Be able to trigger test webhooks https://github.com/Automattic/wp-calypso/issues/65351
TODOs
- [x] Create a new page in developers.wordpress.com to display Swagger UI docs. D85205-code
- [x] Create a schema endpoint that generates a Swagger schema from WP REST API
marketplace/vendorendpoints. D85206-code - [ ] Create a static json file with the docs of the final Licensing API to be displayed on the page created in step 1.
One of the idea for preparing interactive API docs is prepare them using Swagger. You can play with swagger tool https://editor.swagger.io. We can can write code for docs (left pane) and we will have result (right) pane.
We also need to include routes for allowing 3PD to send test events so they can test their integration.
The information should live in developer.wordpress.com/docs/api/
Agreed, that would be nice. It looks like those API docs are currently limited to the old v1.1 endpoints and doesn't extend to the wpcom/v2 WP REST API endpoints (yet).
One of the idea for preparing interactive API docs is prepare them using Swagger
I understand the appeal of interactive API docs yet I'd be concerned about having to maintain code and docs separately, especially when it comes to maintaining these endpoints in the future. Swagger seems to get quite a bit of attention across Automattic (2cf1b-pb/#plain) though it doesn't look like it gets selected a lot.
There's a plugin that parses WP REST API endpoints and generates Swagger docs from it (example), addressing the code/docs separation concern. However, it would still mean that we'd likely have to host these docs on a separate site and link to it from developers.wordpress.com.
@ebinnion Curious if you have a preference/ additional thoughts? It looks like we won't get around some kind of docs generation work, given how developer.wordpress.com currently doesn't offer docs for WP REST API endpoints.
There's a plugin that parses WP REST API endpoints and generates Swagger docs from it (example), addressing the code/docs separation concern. However, it would still mean that we'd likely have to host these docs on a separate site and link to it from developers.wordpress.com.
That's very nice, thanks for the example too! Yes, we can host it in a different site and link to it.
Maybe we could display a swagger output in a child page of P2gHKz-oRE-p2 and adapt the plugin to only show endpoints in the wpcom/v2/marketplace/vendors/ route?
Not sure this was clear to everyone: The scope of this task has expanded to include a static json file with docs for the entire Licensing API so vendors can get started on implementing it on their side while we still work on the endpoints themselves. I updated the issue description to reflect that.
See pdh6GB-1Jt-p2