Add support for defining headers for API methods.

[iliabylich]

To be honest, I couldn't find the tests for views, so I've added tests only for model part. I will add missing tests as soon as somebody tells me where they are 😄

[iliabylich]

partially closes #340

[alan-andrade]

Thanks for this 😎 !
Is it possible to use this with resource_description so that any method description includes these inherited headers ?

[ghost]

@alan-andrade Good point, working on it

[ghost]

@alan-andrade Done, will do rebase after 'plus one'

[mtparet]

👍 good beginning! (next, we should be able to add validation on the headers)

[ghost]

@mtparet I was thinking about validation, do we really need it? As I know, header is always a String (at least, Rack parses it as a String)

class SomeController
  def some_action
    request.headers.keys.map(&:class).uniq
    # => [String]
  end
end

Even if it comes to server as Fixnum, Rack converts it to String

request.headers['SERVER_PORT']
# => '3000'

[iNecas]

Maybe just checking that the required headers are present…

[ghost]

@iNecas do you mean passing required: true option? if so, it's already implemented, check https://github.com/Apipie/apipie-rails/pull/341/files#diff-e61d15662fc6870ce5dcd584e2fd6d11R42

[mtparet]

Yes require should be enough (I was thinking about the 428 Precondition Required http://tools.ietf.org/html/rfc6585#section-3)

[ghost]

@mtparet 428 Precondition Required is not a header, it's a status code, just like 200 OK, so it's out of this PR's scope

[ghost]

Any other comments/missing stuff? I was going to add tests for views, but I couldn't find spec files.

[iNecas]

@IlyaBylich I meant the validate_presence (https://github.com/Apipie/apipie-rails#id20) support for the headers, where,when enabled, it would fail if it's not there. But I can live with this just being documented somewhere.

[iNecas]

No tests for views so far in apipie, no need to add them for this PR

[mtparet]

@IlyaBylich I mean I'm not sure there are cases for which we need to verify the presence of a header except when we need to require a precondition HTTP header. (the absence of a precondition HTTP header could result to a 428 HTTP status)

[ghost]

Added small note that headers can't be validate with validate_presence option (requested by @iNecas ). Rebased into single commit. Basically, ready for merge 😄

P.S. Just a little question about validate_presence config option. Why does the gem for building docs is responsible for params validation?

[alan-andrade]

\ 😃 /
    |
👞  👞

This is great ! Thanks <3

[iNecas]

@iliabylich the validations is maybe the most controversal feature. People either love it or don't understand why it's even there :)

The motivation for it was, given it's ruby code anyway, and it has enough data for doing the checking, why not just leveraging that information. The benefits are:

1. DRY
2. helps keeping the documentation up-to-date: when you forget to document some parameter, it doesn't work, so with it "when not documented, it literally doesn't exist"
3. one of the solutions for mass-assignment issue, alternative to strong parameters

So yes, it doesn't belong to a conventional documentation tool. However, the apipie is quite unconventional :)

ACK from the code perspective: leaving some time for others also confirming they are ok with this PR (seems more people got interested). Expecting a new version with this released early next week

[ghost]

@iNecas ok, it makes sense, I would like to add headers validation (but probably in another PR). And it's nice to hear that you going to release it so soon, I need it in my current project 😄

[iNecas]

New version 0.3.3, with the change was just released. Thanks @iliabylich

[ghost]

@iNecas Thanks for releasing!

[alan-andrade]

This is awesome ! <3 Thanks everyone

[yaneq6]

Hi, what about auto generation headers in docs based on functional tests? It would be a pretty cool feature.

[yaneq6]

I think good idea will be provide an option, to specify list of necessary headers that will be automatically include to docs based on tests.

[iliabylich]

@yaneq6 Any ideas how to differentiate default rails/rack/whatever headers and custom headers? And very often your headers-related stuff like authentication is mocked in your tests, so you can't fetch headers because you just don't have it.

[yaneq6]

@iliabylich As I said, "good idea will be provide an option, to specify list of necessary headers". I mean, everyone who would use this feature should specify list of header in their own scope, somewhere in the config files (maybe apipie.rb or application.rb, whatever...) and only that headers should be automatically included in documentation. But please, don't expect from me any pull request, actually my rails skills are to low and i am not able to implement this feature on my own.

[byjus-taha-abbas]

Missing the following in generation.

add_headers_from_hash(swagger_result, method.resource._headers) if method.resource._headers.present?

[mathieujobin]

@byjus-taha-abbas this PR is 7 years old...
maybe there is an open PR already with the fix you desire.
otherwise, if you can open a PR, I will review it.
please add a test that confirms the new behavior is correct.