smoketurner/dropwizard-swagger

a Dropwizard bundle that serves Swagger UI static content and loads Swagger endpoints.

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.smoketurner:dropwizard-swagger:4.0.5-1'
	}
	dependencies {
		implementation("com.github.smoketurner:dropwizard-swagger:4.0.5-1")
	}
	<dependency>
	    <groupId>com.github.smoketurner</groupId>
	    <artifactId>dropwizard-swagger</artifactId>
	    <version>4.0.5-1</version>
	</dependency>

                            
    libraryDependencies += "com.github.smoketurner" % "dropwizard-swagger" % "4.0.5-1"
        
        

                            
    :dependencies [[com.github.smoketurner/dropwizard-swagger "4.0.5-1"]]

Readme

dropwizard-swagger

Build Status Coverage Status Maven Central GitHub license Become a Patron

A Dropwizard bundle that serves Swagger UI static content and loads Swagger endpoints. Swagger UI static content is taken from https://github.com/swagger-api/swagger-ui

Current version has been tested with Dropwizard 2.0.0 and Swagger 1.6.0 which supports Swagger 2 spec!

Note: if you come from previous versions there have been some changes in the way the bundle is configured, see details below.

License

http://www.apache.org/licenses/LICENSE-2.0

Version matrix

| dropwizard-swagger | Dropwizard | Swagger API | Swagger UI | |--------------------|------------|-------------|------------| | < 0.5 | 0.7.x | 1.3.2 | ? | | 0.5.x | 0.7.x | 1.3.12 | v2.1.4-M1 | | 0.6.x | 0.8.0 | 1.3.12 | v2.1.4-M1 | | 0.7.x | 0.8.x | 1.5.1-M2 | v2.1.4-M1 | | 0.7.2 | 0.8.4 | 1.5.3 | v2.1.2 | | 0.9.x | 0.9.x | 1.5.9 | v2.1.5 | | 1.0.x | 1.0.x | 1.5.12 | v2.2.10 | | 1.1.x | 1.1.x | 1.5.16 | v2.2.10 | | 1.2.x | 1.2.x | 1.5.18 | v3.9.2 | | 1.3.x | 1.3.x | 1.5.22 | v3.23.0 | | 2.0.x | 2.0.x | 1.6.0 | v3.24.3 |

How to use it

  • Add the Maven dependency (available in Maven Central)
<dependency>
    <groupId>com.smoketurner</groupId>
    <artifactId>dropwizard-swagger</artifactId>
    <version>2.0.0-1</version>
</dependency>
  • Add the following to your Configuration class:
public class YourConfiguration extends Configuration {

    @JsonProperty("swagger")
    public SwaggerBundleConfiguration swaggerBundleConfiguration;
  • Add the following your configuration yaml (this is the minimal configuration you need):
prop1: value1
prop2: value2

# the only required property is resourcePackage, for more config options see below
swagger:
  resourcePackage: <a comma separated string of the packages that contain your @Api annotated resources>
  • In your Application class:
@Override
public void initialize(Bootstrap<YourConfiguration> bootstrap) {
    bootstrap.addBundle(new SwaggerBundle<YourConfiguration>() {
        @Override
        protected SwaggerBundleConfiguration getSwaggerBundleConfiguration(YourConfiguration configuration) {
            return configuration.swaggerBundleConfiguration;
        }
    });
}

  • As usual, add Swagger annotations to your resource classes and methods

  • Open a browser and hit http://localhost:<your_port>/swagger

Additional Swagger configuration

To see all the properties that can be used to customize Swagger see SwaggerBundleConfiguration.java

A note on Swagger 2

Host and port do not seem to be needed for Swagger 2 to work properly as it uses relative URLs. At the moment I haven't run through all the scenarios so some adjustments might be needed, please open a bug if you encounter any problems.

Contributors