Generating static docs with springfox, swagger and gradle

Question

I've evaluated the integration of springfox in a simple Spring Boot app exposing few REST API-s. Everything works fine at a first glance - when the application starts I can see the Swagger spec at the JSON endpoint, I can connect and play around with the Swagger UI, Swagger annotations are taken into account, I can generate static HTML docs with the code gen, etc, etc, etc.

What I wonder now is something really simple: how to generate static docs during the build process? I use gradle. During the build the server is apparently down and the JSON endpoint where the swagger spec is is simply not available...

E.g.: code base -> build -> (executable jar + documentation + ... )

Answer 1

I had to generate swagger.json files at build time to take care of API versioning to work properly when passing the version in the Accept header. Did so using Maven though but I guess it can help you as a starting point. FYI, I have done it to document APIs using Spring Boot, Jersey and Swagger and Spring Boot, CXF and Swagger instead of Spring MVC, Swagger and springfox.

Using this plugin might also work for you:

<properties>
    <swagger-maven-plugin.version>3.1.3</swagger-maven-plugin.version>
</properties>
 ...
<plugin>
  <groupId>com.github.kongchen</groupId>
  <artifactId>swagger-maven-plugin</artifactId>
  <version>${swagger-maven-plugin.version}</version>
  <configuration>
    <apiSources>
      <!-- Version 1 -->
      <apiSource>
        <springmvc>false</springmvc>
        <locations>com.asimio.swaggerexample.rest.v1</locations>
        <schemes>http,https</schemes>
        <basePath>/api</basePath>
        <info>
          <title>Multiversion Spring Boot + Jersey + Swagger Demo (Version 1)</title>
          <version>v1</version>
          <description>A multi-version demo (version 1) of a RESTful service using Spring Boot, Jersey and Swagger.</description>
          <termsOfService>http://www.github.com/kongchen/swagger-maven-plugin</termsOfService>
          <contact>
            <email>xxxx@xxxx.xxx</email>
            <name>Orlando L Otero</name>
            <url>http://tech.asimio.net</url>
          </contact>
          <license>
            <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
            <name>Apache 2.0</name>
          </license>
        </info>
        <outputFormats>json</outputFormats>
        <swaggerDirectory>${basedir}/target/classes/static/v1</swaggerDirectory>
        <swaggerApiReader>com.github.kongchen.swagger.docgen.reader.JaxrsReader</swaggerApiReader>
      </apiSource>
      <!-- Version 2 -->
...

More details could be found at: Documenting multiple REST API versions using Spring Boot, Jersey and Swagger