Giters

KittyHeaven / blue_bird

API Documentation Generator for the Phoenix Framework

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

False warning for put/patch when using resources macro

woylie opened this issue · comments

commented

Phoenix.Router.resources defines both a PATCH route and a PUT route for the :update operation. In your controller, you will only have one function for both routes, and that means, you will only define api/3 for either PATCH or PUT. This will lead BlueBird to emit a warning about missing documentation for the other method.

commented

I don't think it's possible to get intel about whether a route was defined via the resources macro. That leaves us with three options:

  1. We leave it as it is and tell our users to ignore the warnings. I wouldn't like that.
  2. We check whether a PATCH route also has a PUT route which was described with the api/3 macro and vice versa. If so, we suppress the warning. In this case, we might have false negatives if an api really handles PATCH and PUT differently. It's not ideal, but at least we get helpful warnings in most cases without annoying users with false warnings.
  3. We remove the warnings altogether. But I found those warnings helpful already, so I'd like to keep them.

What do you think?

commented

I don't like to suppress or ignore warnings either. But we should be able to determine if a route for :put also exists for :patch and vice versa. What do you think about creating the docs for the "undocumented", but yet existing route, automatically? Provided the route is tested.

commented

So let's implement option 2 for now.

As for creating docs for routes without documentation: It would be possible, of course, but we would also have to extract the parameters automatically, because otherwise they wouldn't be displayed in the generated docs. That would make the use of the macros optional. In that case, the warnings should be removed.

This is a fundamental question. Do we want a package that requires explicit documentation and helps you find gaps in your application? Or do we want a package that builds a basic documentation for you out-of-the-box, with the option of adding more descriptions and information as needed, but potentially leading you to treat your documentation half-heartedly?