OAI / OAI/OpenAPI-Specification
No provision to group API's and then $ref it to reference it in other file
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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