OAI / OAI/OpenAPI-Specification

No provision to group API's and then $ref it to reference it in other file

Open
#508 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

re-use: ref-group-combine
Dominant language
Markdown
Stars
31.2k
Forks
9.2k
Avg merge
6h 37m
Merged PRs (30d)
27

Description

In our application, we have apis divided among various modules.

As per swagger-spec, It becomes very difficult to have only one swagger file (api-docs) for all the modules considering the number of apis and also number of teams working on various modules.

So I started using $ref (purpose: same folder reference) and third party swagger parsers to dereference it. But I still cannot figure out a way in swagger to group apis with one $ref.
So that I can assign all apis for a particular module to a team and then just $ref in api-docs that can be dereferenced lately to get complete single api-docs file

Eg:

//something like that
{
    'pet' : '$ref': './pet.json',
    'user' :'$ref': './user.json'
}

Which when dereferenced, will change to

{
    '/pet' : {},
    '/pet/{name}' : {},
    'change/pet' : {},
    '/user': {},
    '/user/data': {}
}

Any help would be appreciated.

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 with the issue's proposed grouped $ref structure and the OpenAPI reference rules, then determine whether the request requires a specification change or only external dereferencing. Done would require a maintainers-approved resolution and documented behavior; the issue names no implementation files or tests.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.