Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify installation of swagger-ui in java webapps #758

Closed
fehguy opened this issue Dec 3, 2014 · 17 comments
Closed

Simplify installation of swagger-ui in java webapps #758

fehguy opened this issue Dec 3, 2014 · 17 comments
Assignees
Milestone

Comments

@fehguy
Copy link
Contributor

@fehguy fehguy commented Dec 3, 2014

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

@webron

This comment has been minimized.

Copy link
Member

@webron webron commented Dec 3, 2014

Including dynamically changing the SwaggerUi settings?

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

@cmoulliard

This comment has been minimized.

Copy link

@cmoulliard cmoulliard commented Dec 3, 2014

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

This comment has been minimized.

Copy link
Contributor Author

@fehguy fehguy commented Dec 3, 2014

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

This comment has been minimized.

Copy link
Contributor Author

@fehguy fehguy commented Dec 29, 2014

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

@ikitommi

This comment has been minimized.

Copy link

@ikitommi ikitommi commented Jan 8, 2015

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

This comment has been minimized.

Copy link
Contributor Author

@fehguy fehguy commented Jan 9, 2015

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

This comment has been minimized.

Copy link

@ikitommi ikitommi commented Jan 9, 2015

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

This comment has been minimized.

Copy link

@ikitommi ikitommi commented Jan 9, 2015

... 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

This comment has been minimized.

Copy link
Contributor Author

@fehguy fehguy commented Feb 1, 2015

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

@fehguy fehguy self-assigned this Mar 26, 2015
@fehguy

This comment has been minimized.

Copy link
Contributor Author

@fehguy fehguy commented Mar 27, 2015

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.

@fehguy fehguy closed this Mar 27, 2015
@jeff9finger

This comment has been minimized.

Copy link

@jeff9finger jeff9finger commented Feb 19, 2016

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

This comment has been minimized.

Copy link

@barun-mishra barun-mishra commented Mar 10, 2016

@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

This comment has been minimized.

Copy link
Member

@webron webron commented Mar 10, 2016

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

@zappee

This comment has been minimized.

Copy link

@zappee zappee commented Apr 1, 2018

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

This comment has been minimized.

Copy link

@jeff9finger jeff9finger commented Apr 1, 2018

@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

This comment has been minimized.

Copy link

@Abhijot Abhijot commented Aug 2, 2019

@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

This comment has been minimized.

Copy link

@sanyarnd sanyarnd commented Dec 11, 2019

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
9 participants
You can’t perform that action at this time.