Simplify installation of swagger-ui in java webapps

[fehguy]

Rather than copying static files into a java webapp directory, we should provide a technique to bundle the artifact cleanly.

[webron]

Including dynamically changing the SwaggerUi settings?

I imagine the bigger issue would be to allow for custom CSS and such.

[cmoulliard]

Here is what we have done for a camel example project to embed swagger-ui into the WAR

https://github.com/apache/camel/blob/master/examples/camel-example-servlet-rest-tomcat/pom.xml

See the different steps declared into the pom.xml

[fehguy]

Along the same lines as @cmoulliard we can do something like this in the pom.xml:

      <plugin>
        <groupId>com.googlecode.maven-download-plugin</groupId>
        <artifactId>download-maven-plugin</artifactId>
        <version>1.2.1</version>
        <executions>
          <execution>
            <id>swagger-ui</id>
            <goals>
              <goal>wget</goal>
            </goals>
            <configuration>
              <url>https://github.com/swagger-api/swagger-ui/archive/v${swagger-ui-version}.tar.gz</url>
              <unpack>true</unpack>
              <outputDirectory>${project.build.directory}</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <artifactId>maven-resources-plugin</artifactId>
        <version>2.6</version>
        <executions>
          <execution>
            <id>copy-resources</id>
            <phase>validate</phase>
            <goals>
              <goal>copy-resources</goal>
            </goals>
            <configuration>
              <outputDirectory>${basedir}/src/main/webapp</outputDirectory>
              <resources>
                <resource>
                  <directory>${project.build.directory}/swagger-ui-${swagger-ui-version}/dist</directory>
                  <filtering>true</filtering>
                  <excludes>
                    <exclude>index.html</exclude>
                  </excludes>
                </resource>
              </resources>
            </configuration>
          </execution>
        </executions>
      </plugin>

Note the excludes will allow the developer to exclude the index.html in this example, or css, etc.

[fehguy]

Will add documentation on the technique, this is now used in swagger-core samples.

[ikitommi]

there are also existing jvm-packages: one is found in webjars (https://github.com/webjars/swagger-ui) & ring-swagger-ui (https://github.com/metosin/ring-swagger-ui). the later one is packaged by us and can be used from Java-based apps just by depending on it: swagger-ui files can be found from classpath resources under /swagger-ui. One can override single files just by placing your own under the same name, works at least so with Leiningen, should work the same way with Maven etc.

Would love to see a configurable jvm-packaged version from the main project.

[fehguy]

The mechanism to include the javascript artifacts in java projects is just not that clear. Can you explain more? For example, most people change the CSS or other, but packaging up swagger-ui as a WAR file, etc will simply not be useful to most. I'm definitely happy to do it, but not sure of the best mechanism.

The webjars is one example, but that too is very specific to how play likes the javascript dependencies (i think).

[ikitommi]

I was thinking in having a dependency to a jar, with just the resources. Created a sample project https://github.com/ikitommi/ring-swagger-ui-demo which has a modified index.html. created with:

lein new compojure-api swagger-ui-demo
cd swagger-ui-demo
mkdir -p resources/swagger-ui
wget https://raw.githubusercontent.com/metosin/ring-swagger-ui/master/resources/swagger-ui/index.html -O resources/swagger-ui/index.html
echo "<h1>Awesome.</h1>" >> resources/swagger-ui/index.html
lein ring uberjar

[ikitommi]

... the beef here is to copy all the resources into the final uberjar/uberwar:

https://github.com/ikitommi/ring-swagger-ui-demo/blob/master/project.clj#L9

One can override resources from the included jars locally, like here just the index.html.

[fehguy]

no fix for this yet, still lots of options, will move to m2

[fehguy]

I'm going to close this out. There are different ways to include swagger-ui into a project, via maven, webjars, npmjs.org, etc. I think this project shouldn't dictate the distribution method.

[jeff9finger]

I used the following to build a war file that includes swagger-ui. YMMV

                    <plugin>
                        <groupId>com.googlecode.maven-download-plugin</groupId>
                        <artifactId>download-maven-plugin</artifactId>
                        <version>1.2.1</version>
                        <executions>
                          <execution>
                            <id>swagger-ui</id>
                            <phase>prepare-package</phase>
                            <goals>
                                <goal>wget</goal>
                            </goals>
                            <configuration>
                              <url>https://github.com/swagger-api/swagger-ui/archive/v${swagger-ui.version}.tar.gz</url>
                              <unpack>true</unpack>
                              <outputDirectory>${project.build.directory}</outputDirectory>
                            </configuration>
                          </execution>
                        </executions>
                    </plugin>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-war-plugin</artifactId>
                        <version>2.6</version>
                        <configuration>
                            <warName>${project.build.finalName}</warName>
                            <webappDirectory>${basedir}/target/${project.build.finalName}</webappDirectory>
                            <webResources>
                                <webResource>
                                    <directory>${project.build.directory}/swagger-ui-${swagger-ui.version}/dist</directory>
                                    <targetPath>swagger-ui</targetPath>
                                </webResource>
                            </webResources>
                        </configuration>
                    </plugin>

[barun-mishra]

@jeff9finger - Did this work for 3.1.0? I am trying the same but seems the download links for tar.gz aren't there for versions 3.1.0.

https://github.com/swagger-api/swagger-ui/releases

[webron]

@barun-mishra - there was never a 3.1.0 release...

[zappee]

The solutin described by @jeff9finger works like a charm except one think:
I need to overwrite the url value in the swagger-ui/index.html file from the default http://petstore.swagger.io/v2/swagger.json to my URL.

Do you have any solution pleaae?

[jeff9finger]

@barun-mishra I have used the same url and set swagger-ui.version to "3.12.0" as a pom property file. And this works.

@zappee We override settings in index.html as well. I will try to describe it here.

We have changed our deployment from a war file to dropwizard, but the concept should be the same. Essentially, create a directory in the "src/main/resources" directory that is the same name as where the swagger-ui application is deployed.
In my case, the directory name is "apidocs", so we created a directory /src/main/resources/apidocs.

Copy the index.html file (or any others that you want to override) into this directory. Update them according to your configuration, and they should overlay the default swagger-ui deployment in the target directory (target/classes/apidocs in my case)

Hope that helps

[Abhijot]

@jeff9finger can I add like this in pom.xml to overwrite the url value in the swagger-ui/index.html file from the default http://petstore.swagger.io/v2/swagger.json to my URL.

`

            <groupId>com.google.code.maven-replacer-plugin</groupId>

            <artifactId>replacer</artifactId>

            <version>1.5.3</version>

            <executions>

                <execution>

                    <phase>prepare-package</phase>

                    <goals>

                        <goal>replace</goal>

                    </goals>

                </execution>

            </executions>

            <configuration>

                <file>${project.build.directory}/swagger-ui-${swagger-ui.version}/dist/index.html</file>

                <replacements>

                    <replacement>

                        <token>http://petstore.swagger.io/v2/swagger.json</token>

                        <value>http://localhost:8080/cameoperson/rest/swagger.json</value>

                    </replacement>

                </replacements>

            </configuration>

        </plugin>
        `

[sanyarnd]

Complete profile example (use webjars + replace url + copy to public directory):

<profile>
    <id>swagger</id>

    <properties>
        <swagger-ui.version>3.24.3</swagger-ui.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.webjars.npm</groupId>
            <artifactId>swagger-ui-dist</artifactId>
            <version>${swagger-ui.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <!-- Unpack swagger dist -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>3.1.1</version>
                <executions>
                    <execution>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>unpack</goal>
                        </goals>
                        <configuration>
                            <artifactItems>
                                <artifactItem>
                                    <groupId>org.webjars.npm</groupId>
                                    <artifactId>swagger-ui-dist</artifactId>
                                    <version>${swagger-ui.version}</version>
                                    <!-- UNPACK DIR -->
                                    <outputDirectory>${project.build.directory}/swagger-dist</outputDirectory>
                                </artifactItem>
                            </artifactItems>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <!-- Fix swagger spec location -->
            <plugin>
                <groupId>com.google.code.maven-replacer-plugin</groupId>
                <artifactId>replacer</artifactId>
                <version>1.5.3</version>
                <executions>
                    <execution>
                        <phase>process-resources</phase>
                        <goals>
                            <goal>replace</goal>
                        </goals>
                    </execution>
                </executions>

                <configuration>
                    <file>
                        ${project.build.directory}/swagger-dist/META-INF/resources/webjars/swagger-ui-dist/${swagger-ui.version}/index.html
                    </file>
                    <replacements>
                        <replacement>
                            <token>https://petstore.swagger.io/v2/swagger.json</token>
                            <value>swagger.yaml</value> <!-- SWAGGER FILE -->
                        </replacement>
                    </replacements>
                </configuration>
            </plugin>

            <!-- Copy artifacts -->
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>copy-swagger-to-webroot</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <!-- OUTPUT DIR (webroot, public) -->
                            <outputDirectory>${project.build.outputDirectory}/webroot/swagger-ui</outputDirectory>

                            <includeEmptyDirs>true</includeEmptyDirs>
                            <resources>
                                <resource>
                                    <directory>
                                        ${project.build.directory}/swagger-dist/META-INF/resources/webjars/swagger-ui-dist/${swagger-ui.version}/
                                    </directory>
                                    <filtering>false</filtering>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</profile>