Giters

KittyHeaven / blue_bird

API Documentation Generator for the Phoenix Framework

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Query param values missing

mmcc opened this issue · comments

commented

I'm running into an odd problem where query params seem to almost work in the output, but not quite. Instead of seeing the params used in the actual test request, I get something like https://api.example.com/v1/foo?group_by=&timeframe=. The params used do show up, just as empty values.

I'll try to dig into this on my end, figured I'd go ahead and open an issue in the meantime in case someone else has seen this.

Thanks for taking this project over!

commented

Hi @mmcc,

I'm not entirely sure what you mean. Where exactly do you expect the parameter values to appear?

commented
commented

I would expect the parameters to include the values used in the response, or not be there at all, but the current feels confusing at best. It could be that I'm missing something entirely, but I think I'd rather the query params not be in the example at all.

Here's an example:

In the controller:

api :GET, "/v1/foo" do
  title "foo example"
  description "This is an example"
  parameter :group_by, :string, [optional: true, description: "Field to group the data by"]
  parameter :timeframe, :array, [optional: true, description: "Timeframe array", default: ["24:hours"]]
  parameter :page, :integer, [optional: true, description: "Current page"]
  parameter :filters, :object, [optional: true, description: "Filter key pairs"]
end

Algolia output

image

So, I think part of the confusion here is that only the query params used in the test are passed through to either of the examples, but their values are ignored. I would expect the URL on the right to have the values that were used in the test, i.e.,

GET https://api.example.com/v1/foo?group_by=os&timeframe="24:hours"

Hope this helps!

commented

Now I understand what you mean. If you want to display some values in the url, you have to define the example key in the parameter options. For example:

parameter :group_by, :string, [
  optional: true,
  description: "Field to group the data by",
  example: "os"]

The url displayed in the right column is generated by aglio, and aglio uses the example values of the parameter definitions for this. The api blueprint specification does not allow to specify different example values per request. If we were to extract the example values from the test requests automatically, we would have to arbitrarily choose a single query parameter value out of all the tests for the route. I'd rather not do that.

commented

Got it. Yeah, that's fair enough, I think it's just a little confusing that the API request example URL could be largely unrelated from the example request below it. Sounds like this is more an API Blueprint / Algolia limitation than BlueBird, though.

On the parameter front, I'm currently generating the apib file and going back and manually adding in the request body parameters manually. Unless I'm mistaken, BlueBird currently only supports documenting URI parameters. Is this on your radar or should we consider jumping on that ourselves? Not a big deal in the short term, but long term it'd be nice to have everything documented in the api DSL.

commented

You are right, currently it is only possible to describe path and query parameters.

The API Blueprint specification handles body parameters separately. You can describe body parameters in the attributes section.

In Swagger, you can describe the body parameters by defining a single body parameter with a schema object.

I'd like to see better handling of request bodies and body parameters in the future, but I'm not working on that right now. So if you want to have a go at it, go ahead! Before implementing anything, we should first think about how to solve all the steps in a nice way:

  1. Extracting the request bodies / body parameters. (Currently, we only read the body_params from the Plug.Conn. Can/should we extract the original body somehow in the tests?)
  2. Providing a dsl to describe those body parameters. Should the body parameters be described the same way as the path and query parameters, or should they be handled with an additional macro parameter (by taking a hint from api blueprint and adding attributes to the api macro)?
  3. Creating an internal representation from the logged test requests and the api macro descriptions.
  4. Converting the internal representation to both api blueprint and swagger format.