Swagger UI endpoint authorization.

[texpert]

This helps to guard Swagger UI endpoints adding 3 new options to swagger documentation (in my case, using WineBouncer gem and Doorkeeper, but it is configurable):

endpoint_auth_wrapper: WineBouncer::OAuth2,
swagger_endpoint_guard: "oauth2 false",
oauth_token: 'doorkeeper_access_token'

To display the endpoint only for signed admin users, I am using a lambda (I think a few lambdas like this would go to options as well - I will work it later):

  not_admins = lambda { |token=nil| token.nil? || !User.find(token.resource_owner_id).admin? }

  resource :users, desc: "Users' operations" do
    desc 'List users', hidden: not_admins
    oauth2 'admin'
    get do
      render_result User.all
    end

Notes:

• Using with Rails, 'rails' and 'wine_bouncer' gems should be required prior to 'grape-swagger' in boot.rb;
• This works with a fresh PR to WineBouncer which is yet unmerged - Code refactoring antek-drzewiecki/wine_bouncer#64.

[LeFnord]

@texpert … nice work, but can you add a spec please

[texpert]

@LeFnord , here is the spec, finally :)

Rubocop's complaining about double negation !!, it is the only fail (and I think this cop is ambiguos.
!! looks much better here than some ternary ? to get true or false value) - what do you think?

[LeFnord]

@texpert … please rebase and try to use .present? to avoid rubocop warning, thanks

[LeFnord]

👍 … good work 😄

[texpert]

Thanks, @LeFnord!

I am prepairing one last commit to fix some nuances in the README, and after this I will squash.

[texpert]

Done!

[narze]

For some people wonder on how to use basic auth to protect the endpoint, here's my implementation after some trial & error.

class BasicAuthWrapper < Grape::Middleware::Base
  def before
    path_is_swagger_doc = context.options[:for].try(:mount_path)&.include?("/swagger_doc")

    if path_is_swagger_doc && !basic_auth(env['HTTP_AUTHORIZATION'])
      context.error!('401 Unauthorized', 401)
    end
  end

  private

  def basic_auth(auth_header_string)
    return false if !auth_header_string || !auth_header_string.start_with?('Basic ')

    auth_header_string = auth_header_string.gsub(/^Basic /, '')
    decoded_str = Base64.decode64(auth_header_string)
    
	decoded_str == "username:password"
  end
end

# Usage: Add class to `endpoint_auth_wrapper` option
add_swagger_documentation(
  base_path: '/api',
  doc_version: 'v1',
  add_version: true,
  mount_path: '/v1/swagger_doc',
  endpoint_auth_wrapper: BasicAuthWrapper