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

[mkeshavgarg]

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.

[webron]

Sorry, but I really don't follow the question. Can you provide further details?

[mkeshavgarg]

Suppose we have two modules pet and user. Both these modules have few apis which is to be documented using swagger

pet (Module 1):

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

user (Module 2):

{
   '/user': {};
   '/user/data': {}
}

Now as per swagger rules and using '$ref' final api-docs would look like:

    paths: {
        '/pet' : {
            '$ref': './pet.json#/pet', 
        },
        '/pet/{name}' : {
            '$ref': './pet.json#/petName'
        },
        'change/pet' : {
            '$ref': './pet.json#/changePet',
        },
        '/user': {
            '$ref': './user.json#/user',
        },
        '/user/data': {
            '$ref': './user.json#/userData',
        }
    }

But no. of such modules and no. of apis per module can vary largely and it becomes difficult to ask teams associated with particular modules to document each api separately in api-docs file

With module wise separation of apis:

    paths: {
        'pet':{
            '$ref': './pet.json',
        },
        'user':{
            '$ref': './user.json',
        }
    }

Such swagger json would be much cleaner and easier for teams to work with

[webron]

That's closer to the concept of microservices documentation which doesn't exist in 2.0. There are several existing discussions on it in this repo and other forums.

[fehguy]

Parent issue #560

[earth2marsh]

FWIW, I've felt this pain, too. The "module wise separation of APIs" example at the end is the best suggestion I've seen, but it still feels forced. Sadly, I don't have a better proposal to make.