search

miragejs / discuss

Ask questions, get help, and share what you've built with Mirage
MIT License
2 stars 0 forks source link

Feature Request: Generate API docs from test runs #55

Open patrickberkeley opened 4 years ago

patrickberkeley commented 4 years ago

A lot of API docs include sample responses for each endpoint e.g., see THE CHARGE OBJECT on https://stripe.com/docs/api/charges/object.

Currently with Mirage when tests are run you can easily add a logger to each endpoint defined in mirage/config.js e.g., console.log(this.serialize(books.all()));.

This issue is a feature request to add the ability to mirage to automatically generate a JSON structure with all the request objects from the endpoints that were hit in each test run. The idea being the JSON could be used:

  1. By a documentation tool to render example response objects
  2. As a tool for UI teams to share with API teams as the expected frontend data contract
  3. As either an automated or manual check between what the UI expects the data structure to be and what the API actually exposes
samselikoff commented 4 years ago

Great use cases - these have definitely been brought up before and I think the solution here is to add a middleware layer to Mirage that makes this sort of thing easy.

I am nearly done with the Mirage tutorial, after which our priorities are

  1. Bugfixes
  2. Launch v1.0 (of miragejs)
  3. Get to prioritized feature work

At the top of prioritized feature work is middleware, and improving passthrough. But I'm glad you opened this because it's good to hear from folks who could benefit from a middleware system. I think it's definitely miragejs/ember-cli-mirage#1 or miragejs/ember-cli-mirage#2 in terms of priority.

(Heya Patrick! 👋 Hope you are doing well)

patrickberkeley commented 4 years ago

Thanks for the info, Sam! Hope you are doing well too! 👋 Please feel free to close this issue if you'd like.

samselikoff commented 4 years ago

Transferred it over to our /discuss repo since it's not actionable ATM but thanks again for dropping these ideas in! 👍