[MGNLREST-155] REST: Improved Interactive API explorer Created: 28/Nov/17  Updated: 26/Jun/23

Status: Open
Project: Magnolia REST Framework
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Story Priority: Neutral
Reporter: Christopher Zimmermann Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
dependency
depends upon MGNLREST-204 Publish openAPI specs for delivery en... Accepted
Template:
Acceptance criteria:
Empty
Task DoD:
[ ]* Doc/release notes changes? Comment present?
[ ]* Downstream builds green?
[ ]* Solution information and context easily available?
[ ]* Tests
[ ]* FixVersion filled and not yet released
[ ]  Architecture Decision Record (ADR)
Epic Link: Headless Backlog

 Description   

REST: Interactive API explorer

User story:

As a Developer, I have comprehensive interactive API explorer (documentation) so that I can discover available endpoints, explore how they work, and be productive right away.

As a Developer, I want other developers to understand the endpoints that I have created, so they can be productive and dont bother me with questions.

Capabilities:

  • OOTB endpoints can be explored in API explorer.
  • Configured endpoints are displayed and can be explored in API explorer. (Delivery endpoints, and any future configured endpoints.)
  • API explorer provides sample curl commands.
  • Endpoints can be explored in the context of Admincentral.
  • As a project developer I can easily expose an API explorer to 3rd party developers that do not have access to AdminCentral.
    • It is possible to embed API explorer in Magnolia documentation pages.

It would be worth considering a two-column / three-column API explorer as has become very common in API documentation.

Perhaps it can be based on the same swagger.json file?

 

Popular API docs use a 2-column or 3-column layout as popularised on the STRIPE API page.
(https://stripe.com/docs/api#expanding_objects)
As the UX is attractive and useful and familiar, it would be worth finding out if this would be easy to accomplish based on our Swagger setup.

Some resources:

https://github.com/jensoleg/swagger-ui
https://github.com/lord/slate
https://github.com/sourcey/spectacle
https://tech.trustpilot.com/an-evaluation-of-auto-generated-rest-api-documentation-uis-53031753a789


Generated at Mon Feb 12 06:57:09 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.