ruby-grape / ruby-grape/grape-swagger

Multiple swagger endpoints for multiple API versions?

Open
#141 10 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

confirmed bug needs work/investigation swagger-1.2
Dominant language
Ruby
Stars
1.1k
Forks
479
Avg merge
2d 14h
Merged PRs (30d)
6

Description

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?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing add_swagger_documentation and how the mounted API classes expose their version information. Check how the current documentation combines the v1 and admin.v1 mounts, then determine the configuration needed to produce separate /docs/v1 and /docs/admin.v1 documents. Done means Swagger UI can load each URI without duplicate endpoints from the other version.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, ruby
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.