Multiple swagger endpoints for multiple API versions?

[mepatterson]

Is there a way to do this, or am I missing something... ?

I have:

module API
  class Base < GrapeApi::API
    mount API::V1::Robots
    mount API::V1::Pirates
    mount API::V1::Ninjas
    mount API::AdminV1::Robots
    mount API::AdminV1::Activities
  end
end

Within each of those mounted classes, I specify the proper version, so there are two discrete versions in my API system ("v1" and "admin.v1")

add_swagger_documentation works, and documents all of the endpoints on all of those API mounts, but I get a bunch of duplicates -- /robots (v1) and /robots (admin.v1), for example -- with no real way to distinguish them, since Swagger UI doesn't know how to distinguish.

What I would like to do is be able to add_swagger_documentation for all the V1s responding to "/docs/v1" and all the admin endpoints responding to "/docs/admin.v1" ... so effectively it would be running grape-swagger twice, but separating those versions. And then I can just point Swagger UI at whichever URI I want, depending on which version of docs I want to look at.

Is this supposed to work automatically with grape-swagger, or am I missing something?

[dblock]

I think half of the problem is that Grape namespaces != grape-swagger namespaces. Grape-swagger just magically believes that the first part of the path is a namespace. Throw in versioning and it gets even more confused. I think we need to fix that first and then we can also start distinguishing various API mounts from a single add_swagger_documentation.

[LeFnord]

still an issue?

[yeonhoyoon]

It does work, you just need to specify different mount_path for different apis.

[mcfilib]

@yeonhoyoon don't suppose you can explain how to get that to work? i'm giving it try just now but not really having much luck.

[yeonhoyoon]

@mcfilib

class FooApiRoot < Grape::API
  mount CarApi
  mount TrainApi

  add_swagger_documentation(...)
end

class BarApiRoot < Grape::API
  mount DogApi
  mount CatApi

  add_swagger_documentation(...)
end

You will have two different swagger endpoints with the above setup.
Hope it helps.

[mcfilib]

that does help, thanks!

[morcoteg]

Currently experiencing this problem. We use the Accept-Version header, and simply changing the mount_path: to be more custom isn't solving the problem. I noticed that invoking add_swagger_documentation works from a root level API definition, but not from a nested one. Any suggestions? Looked like this was raised in grape-swagger-rails as an issue, but based on the README, I'm not seeing any suggestions for workarounds for this issue below.

Example:

module Graduates
  class API < ::Grape::API
    mount ::Graduates::V1::API
    mount ::Graduates::V2::API
  end
end

module Graduates
  module V1
    class API < ::Grape::API
      version 'v1.0.0', strict: true, using: :accept_version_header

      #various example mounts

      add_swagger_documentation \
        mount_path: 'v1_swagger.json'
    end
  end
end

module Graduates
  module V2
    class API < ::Grape::API
      version 'v2.0.0', strict: true, using: :accept_version_header

      #various example mounts

      add_swagger_documentation \
        mount_path: 'v2_swagger.json'
    end
  end
end

In this example, when attempting to access either v1_swagger.json or v2_swagger.json, I get a 404. But I don't when invoking add_swagger_documentation from the root, Graduates::API.

[morcoteg]

update - getting rid of strict: true fixed my issue above... not entirely sure why... I wonder if it has something to do with Swagger UI not sending the request with the proper Accept-Version header, maybe there's a way to define headers in swagger UI, or some related rails initializer.

[dblock]

With strict: true you're getting a 406 without the proper Accept-Version header, so when it comes to Swagger you probably get the effect of that routing. I could be wrong, a spec would be helpful.

[Faisal-nfl]

@morcoteg how do you access swagger docs with this
like we mount this

mount API, at: "/"
mount GrapeSwaggerRails::Engine => "/docs"

how BASE_URL/docs 'll differentiate b/w v1_swagger & v2_swagger