ruby-grape / grape-swagger

Add OAPI/swagger v2.0 compliant documentation to your grape API
MIT License
1.09k stars 471 forks source link

swagger-grape doesn't generate swagger documentation after adding an API #937

Open ngw opened 1 month ago

ngw commented 1 month ago

I'm using Grape with grape-swagger, entities and representable. Everything works very well (over several projects) until I add this API:

    module SearchService
      module Api
        class Queries < SearchService::App
          desc "Returns a list of tickets",
               success: [
                 { code: 200, model: SearchService::Entities::Ticket, is_array: true }
               ]

          params do
            # many params
          end
          get do
          end

          desc "Saves a query",
               success: [
                 { code: 201, model: SearchService::Entities::Query }
               ]
          params do
            # many params
          end
          post do
          end

          route_param :tenant, documentation: { param_type: "string" } do
            desc "Fetches all queries for a tenant",
                 success: { code: 200, model: SearchService::Entities::Query }
            get do
            end
          end
        end
      end
    end

For some reason, the GET with the route_param crashes the swagger generation, which returns an empty array (and obviously nothing else works). I've used similar code all over the place, but the only way to make this work is to remove the last API. I'm incredibly confused and attempted to debug this for hours, can anybody give me a hand? By inspecting the routes, everything looks fine, but url/swagger_doc is []...

Grape is used outside RoR, and all versions are the latest.

The reason I'm adding an issue is that I've used this kind of code over several project and this is the only place where I have this issue, and it doesn't really fail with an explanation, it just generates something I can't understand...

 ngw@abulafia  ~/Projects/chorally/search-service   dev ±  docker compose run -e SEARCH_SERVICE_ENV=test api bundle exec rake oapi:fetch -- store=true
[+] Creating 2/0
 ✔ Container opensearch-node        Running                                                                                                                                                                                                                                                                                                       0.0s
 ✔ Container opensearch-dashboards  Running                                                                                                                                                                                                                                                                                                       0.0s
/usr/local/bundle/ruby/3.3.0/gems/zeitwerk-2.6.17/lib/zeitwerk/kernel.rb:34: warning: syslog was loaded from the standard library, but will no longer be part of the default gems since Ruby 3.4.0. Add syslog to your Gemfile or gemspec. Also contact author of logging-2.4.0 to add syslog into its gemspec.
rake aborted!
NoMethodError: undefined method `keys' for nil (NoMethodError)

        JSON.parse(@oapi).keys.first == 'error'
                         ^^^^^
/usr/local/bundle/ruby/3.3.0/gems/grape-swagger-2.1.0/lib/grape-swagger/rake/oapi_tasks.rb:115:in `error?'
/usr/local/bundle/ruby/3.3.0/gems/grape-swagger-2.1.0/lib/grape-swagger/rake/oapi_tasks.rb:111:in `save_to_file?'
/usr/local/bundle/ruby/3.3.0/gems/grape-swagger-2.1.0/lib/grape-swagger/rake/oapi_tasks.rb:52:in `block (2 levels) in fetch'
/usr/local/bundle/ruby/3.3.0/gems/grape-swagger-2.1.0/lib/grape-swagger/rake/oapi_tasks.rb:49:in `each'
/usr/local/bundle/ruby/3.3.0/gems/grape-swagger-2.1.0/lib/grape-swagger/rake/oapi_tasks.rb:49:in `block in fetch'
/usr/local/bundle/ruby/3.3.0/gems/rake-13.2.1/exe/rake:27:in `<top (required)>'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/cli/exec.rb:58:in `load'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/cli/exec.rb:58:in `kernel_load'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/cli/exec.rb:23:in `run'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/cli.rb:455:in `exec'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/vendor/thor/lib/thor/command.rb:28:in `run'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/vendor/thor/lib/thor/invocation.rb:127:in `invoke_command'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/vendor/thor/lib/thor.rb:527:in `dispatch'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/cli.rb:35:in `dispatch'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/vendor/thor/lib/thor/base.rb:584:in `start'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/cli.rb:29:in `start'
/usr/local/bundle/gems/bundler-2.5.18/exe/bundle:28:in `block in <top (required)>'
/usr/local/bundle/gems/bundler-2.5.18/lib/bundler/friendly_errors.rb:117:in `with_friendly_errors'
/usr/local/bundle/gems/bundler-2.5.18/exe/bundle:20:in `<top (required)>'
/usr/local/bundle/bin/bundle:25:in `load'
/usr/local/bundle/bin/bundle:25:in `<main>'
Tasks: TOP => oapi:fetch
(See full trace by running task with --trace)

As you can probably guess, this error is because it's generating [] which obviously isn't a Hash.