Una forma 'simple' de implementar Swagger en una aplicación Spring MVC

85

Tengo una API ReSTFul escrita en Spring simple (¡sin Spring Boot, sin cosas elegantes!). Necesito implementar Swagger en esto. Hasta ahora, CADA página de Internet solo me ha vuelto loco con configuraciones confusas y código inflado que no encontré portátil en absoluto.

¿Alguien tiene un proyecto de muestra (o un conjunto de pasos detallados) que pueda ayudarme a lograr esto? En particular, estoy buscando una buena muestra que use swagger-springmvc. Sé que tiene "muestras", pero en el mejor de los casos, el código esotérico es desalentador.

Debo aclarar que no estoy buscando "por qué Swagger es simplemente el mejor". No estoy usando (y para mi tarea actual no usaré) Spring Boot o tal.

wavicle
fuente
4
Por las muestras, supongo que te refieres a github.com/adrianbk/swagger-springmvc-demo . De hecho, le animo a que abra un ticket directamente en swagger-springmvc, ya que es importante para ellos saber que algunos de sus usuarios potenciales pueden sentir que los documentos son inadecuados para poder mejorarlos.
Ron

Respuestas:

122

Springfox (Swagger spec 2.0, actual)

Springfox ha reemplazado a Swagger-SpringMVC y ahora es compatible con las especificaciones 1.2 y 2.0 de Swagger. Las clases de implementación han cambiado, lo que permite una personalización más profunda, pero con algo de trabajo. La documentación ha mejorado, pero aún es necesario agregar algunos detalles para la configuración avanzada. La respuesta anterior para la implementación 1.2 todavía se puede encontrar a continuación.

Dependencia de Maven

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency> 

La implementación mínima se ve más o menos igual, pero ahora usa la Docketclase en lugar de la SwaggerSpringMvcPluginclase:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

La documentación de la API de Swagger 2.0 ahora estará disponible en http://myapp/v2/api-docs.

Nota: Si no está utilizando Spring Boot, debe agregar la dependencia jackson-databind. Dado que springfox usa jackson para el enlace de datos.

Agregar la compatibilidad con la interfaz de usuario de Swagger es aún más fácil ahora. Si está utilizando Maven, agregue la siguiente dependencia para el webjar de la interfaz de usuario de Swagger:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

Si está utilizando Spring Boot, su aplicación web debería recoger automáticamente los archivos necesarios y mostrar la interfaz de usuario en http://myapp/swagger-ui.html(anteriormente:) http://myapp/springfox. Si no está utilizando Spring Boot, como menciona yuriy-tumakha en la respuesta a continuación, deberá registrar un controlador de recursos para los archivos. La configuración de Java se ve así:

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override 
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

La nueva función de generación de documentación estática también se ve bastante bien, aunque no la he probado yo mismo.

Swagger-SpringMVC (Swagger spec 1.2, anterior)

La documentación de Swagger-SpringMVC puede ser un poco confusa, pero en realidad es increíblemente fácil de configurar. La configuración más simple requiere crear un SpringSwaggerConfigbean y habilitar la configuración basada en anotaciones (lo que probablemente ya haga en su proyecto Spring MVC):

<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

Sin embargo, creo que vale la pena dar el paso adicional de definir una configuración Swagger personalizada usando SwaggerSpringMvcPlugin, en lugar del bean anterior definido por XML:

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    @SuppressWarnings("SpringJavaAutowiringInspection")
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*api.*"); // assuming the API lives at something like http://myapp/api
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

Cuando ejecute su aplicación, ahora debería ver su especificación de API creada en http://myapp/api-docs. Para configurar la elegante interfaz de usuario de Swagger, debe clonar los archivos estáticos del proyecto GitHub y ponerlos en su proyecto. Asegúrese de que su proyecto esté configurado para entregar archivos HTML estáticos:

<mvc:resources mapping="*.html" location="/" />

Luego edite el index.htmlarchivo en el nivel superior del distdirectorio de la IU de Swagger . Hacia la parte superior del archivo, verá algo de JavaScript que se refiere a la api-docsURL de otro proyecto. Edite esto para que apunte a la documentación Swagger de su proyecto:

  if (url && url.length > 1) {
    url = url[1];
  } else {
    url = "http://myapp/api-docs";
  }

Ahora, cuando navegue hacia http://myapp/path/to/swagger/index.html, debería ver la instancia de la IU de Swagger para su proyecto.

woemler
fuente
1
@MikhailBatcer: He actualizado la respuesta con la dependencia de Maven para Springfox. Esta es la única dependencia que debe incluir en su proyecto, a menos que también desee Swagger UI o Static Docs.
woemler
2
parece que la URL de la interfaz de usuario ahora es /myapp/swagger-ui.html y no / springfox
chrismarx
7
Para completar: el método 'regex' en el ejemplo de springfox 'SwaggerConfig' es de 'springfox.documentation.builders.PathSelectors.regex (String)'. Me tomó bastante tiempo darme cuenta de eso;)
cheneym
2
Me tomé la libertad de agregar PathSelectors.para ayudar a las personas que luchan con la importación estática deregex
Tim Büthe
1
Vale la pena señalar: si sigue estas instrucciones exactamente y no usa SpringBoot, obtendrá un error de tiempo de ejecución debido a las diferentes versiones de las bibliotecas springfox y springfox-ui recuperadas de Maven. En su lugar, comience con la última versión de ambos si es posible ( 2.5.0mientras escribo esto)
Kip
13

La interfaz de usuario de Springfox Swagger me funciona después de agregar la dependencia de WebJar y las asignaciones de recursos. http://www.webjars.org/documentation#springmvc

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.3.5</version>
    </dependency>

spring-servlet.xml:

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

o anotación de primavera https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java

Swagger2 debería estar habilitado

 @EnableSwagger2
 public class SwaggerConfiguration {
 }
Yuriy Tumakha
fuente
Esto me ayudó mucho, sin embargo, todavía obtengo un 404 /swagger-resourcesal abrir swagger-ui.html. ¿Algun consejo? ¿Quizás más asignaciones de recursos?
Tim Büthe
Parece que los recursos de swagger no están en el contexto raíz. Puede solucionarse asignando DispatcherServlet al contexto raíz. Mire el problema de solución de problemas 983 y P. ¿Cómo se configura swagger-ui para aplicaciones que no son Springboot?
Yuriy Tumakha