Using swagger-codegen with multiple swagger files

Question

Our project uses multiple swagger files for a single API, yet it appears swagger-codegen only accepts one. How do we generate code with swagger-codegen in this case?

Fitz

Answer 1

You can use relative schema file. e.g.

$ref: 'Pet.yaml'

Ref: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#relative-schema-file-example

If the swagger files are not linked/related to each other, then you will need to combine the swagger files into a single file and use tags to classify the operations. e.g.

• https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#L14
• https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#L32

Vu

@wing383 Thank you, does this suggest that a master swagger file should be created that somehow that links them all together? Currently there are six JSON swagger files, and all have their own info and tags, and together they define a single API. Is this an uncommon approach? – Fitz

I saw developers breaking down a huge API into smaller APIs with several Swagger spec before as they want to avoid putting too many endpoints/operations into a single API. Size of the SDK may become a problem in certain scenarios so keeping the SDK size small is not a bad idea. Whether to combine the APIs into a single one or not really comes down to your use case. – Vu

Thanks, although I'm still not sure how to combine them for local use or how $ref helps. I'm working with the source swagger files, although somehow the company I work for combines them into a single file for public consumption with the docs. I'm hoping to do the same locally while testing that isn't manually copy-n-paste or hacking together a script to combine them. – Fitz

Hi @WilliamCheng, I have a similar issue. I have more then two (JSON) api definitions but I want to document them like a single API documentation. Any way to achieve this ? – Baluster

Answer 2

Try swagger-combine-maven-plugin:
    <plugin>
       <groupId>com.randomnoun.maven.plugins</groupId>
       <artifactId>swagger-combine-maven-plugin</artifactId>
       <version>1.0.0</version>
       <executions>
          <execution>
             <id>swagger-combine-1</id>
             <phase>generate-sources</phase>
             <goals>
                <goal>swagger-combine</goal>
             </goals>
             <configuration>
                <fileset>
                   <includes>
                      <include>1.yaml</include>
                      <include>2.yaml</include>
                      <include>common.yaml</include>
                   </includes>
                   <directory>${project.basedir}/src/apispecs/v1</directory>
                </fileset>
                <outputDirectory>${project.basedir}/src/apispecs/v1</outputDirectory>
                <finalName>single-partial.yaml</finalName>
             </configuration>
          </execution>
          <execution>
             <id>swagger-combine</id>
             <phase>generate-sources</phase>
             <goals>
                <goal>swagger-combine</goal>
             </goals>
             <configuration>
                <fileset>
                   <includes>
                      <include>*.yaml</include>
                   </includes>
                   <directory>${project.basedir}/src/apispecs/v1</directory>
                </fileset>
                <outputDirectory>${project.basedir}/src/apispecs/v1</outputDirectory>
                <finalName>single.yaml</finalName>
             </configuration>
          </execution>
       </executions>
    </plugin>

Furst

Your answer could be improved with additional supporting information. Please edit to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers in the help center. – Weka