Uploaded image for project: 'Magnolia REST Framework'
  1. Magnolia REST Framework
  2. MGNLREST-155

REST: Improved Interactive API explorer

    XMLWordPrintable

Details

    • Story
    • Resolution: Unresolved
    • Neutral
    • None
    • None
    • None
    • None

    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

      Checklists

        Acceptance criteria

        Attachments

          Issue Links

            Activity

              People

                Unassigned Unassigned
                czimmermann Christopher Zimmermann
                Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                  Created:
                  Updated:

                  Checklists

                    Task DoD