search

danielgtaylor / aglio

An API Blueprint renderer with theme support that outputs static HTML
4.75k stars 480 forks source link

Working with huge list of URI parameters #323

Open bgaillard opened 7 years ago

bgaillard commented 7 years ago

Hi, we have an API with collection endpoints accepting huge number of filter URI parameters (more than 50).

We would like to document everything, but the problem is that aglio generates an horrible template URI with all the URI parameters.

For example.

GET /products{?param1,param2,param3,param4,param5,param6,param7,param8,param9,param10,param11}.

IMO generating URI templates is only "visually friendly" with very simple APIs, this is not the case with real world APIs.

So my question is, do we have any solution to prevent Aglio to generate those URI parameters is the rendered URI template ?

For my case generating only GET /products would be sufficient because the documentation of all the parameters is rendered after.

Thanks

codeodor commented 6 years ago

Did you ever find a solution for this?

bgaillard commented 6 years ago

Hi @codeodor, we worked on this a long time ago. After looking our project it seems we simply did not use URI template parameters. We document parameters but without URL template parameters.

For now its "acceptable" but not perfect, so we did not found a real solution for this problem.

Let me know if you find a solution.

Thanks

codeodor commented 6 years ago

What I ended up doing was changing our examples to send a JSON body instead of URL params. That gave nice output, and was more along the lines of what we actually want to support anyway.