swagger-codegen files location

9.8k views Asked by At

I am playing with swagger-codegen on a project and I end up asking myself a question: Is there any convention for the location of the swagger files?

Here is my case:
I'm using Maven for my project, so I have the standard Maven structure:

pom.xml
src
|--main
   |--java
   |--resources
   |--webapp
|--test
   |--java
   |--resources

To make my REST API generated with Swagger, I have to put the swagger.json, some mustache templates and the .swagger-codegen-ignore somewhere. I have put them (naturally?) in src/main/resources:

resources
|--api
   |--v2
      |--swagger.json
|--swaggerconfig
   |--api.mustache
   |--[...]
|--.swagger-codegen-ignore

I have configured my pom.xml with the proper swagger-codegen-maven-plugin and set the packaging to war so I get my war generated (in order to deploy it in Tomcat). An extract:

[...]
<packaging>war</packaging>
[...]
<build>
  <finalName>my-project</finalName>
  <plugins>
    <plugin>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-codegen-maven-plugin</artifactId>
      <version>2.2.1</version>
      <executions>
        <execution>
          <phase>generate-sources</phase>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${basedir}/src/main/resources/api/v2/swagger.json</inputSpec>
            <language>jaxrs</language>
            <templateDirectory>${basedir}/src/main/resources/swaggerconfig</templateDirectory>
            <addCompileSourceRoot>true</addCompileSourceRoot>
            <configOptions>
              <library>jersey2</library>
            </configOptions>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <!-- .swagger-codegen-ignore must be located at the root as per documentation -->
    <plugin>
      <artifactId>maven-resources-plugin</artifactId>
      <version>3.0.2</version>
      <executions>
        <execution>
          <id>copy-resources</id>
          <phase>validate</phase>
          <goals>
            <goal>copy-resources</goal>
          </goals>
          <configuration>
            <outputDirectory>${basedir}/target/generated-sources/swagger</outputDirectory>
            <resources>
              <resource>
                <directory>${basedir}/src/main/resources</directory>
                <includes>
                  <include>.swagger-codegen-ignore</include>
                </includes>
              </resource>
            </resources>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

After a mvn install my swagger generated files are generated and compiled successfully, the war gets generated and is working fine.
However, in the generated war, inside WEB-INF/classes folder I find my api and swaggerconfig folders, and the .swagger-codegen-ignore. Well, this is normal as they were packaged in the src/main/resources.

Long story short: Should I put those files elsewhere (like a src/main/swagger so Maven does find them by default)? Should I write some inclusion/exclusion rules in a maven-war-plugin (but I feel like this is not a good practice)? I have found no clear documentation on this on swagger Github.

Thanks

0

There are 0 answers