spring - enableswagger2 - swagger example java

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

Question

Tengo una API ReSTFul escrita en Spring simple (¡sin Spring Boot, sin cosas elegantes!). Necesito implementar Swagger en esto. Hasta ahora, CADA página en Internet solo me ha vuelto loco con configuraciones confusas y código hinchado 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.

Answer 1

Springfox (Swagger spec 2.0, actual)

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

Dependencia 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 clase Docket lugar de la clase SwaggerSpringMvcPlugin :

@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, entonces debe agregar la dependencia jackson-databind. Desde springfox usa jackson para el enlace de datos.

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

<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, entonces, 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 para 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 bean SpringSwaggerConfig y habilitar la configuración basada en anotaciones (que probablemente ya haya hecho 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 extra de definir una configuración personalizada de Swagger utilizando SwaggerSpringMvcPlugin , en lugar del anterior bean 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 sofisticada interfaz de usuario de Swagger, debe clonar los archivos estáticos del proyecto GitHub y colocarlos en su proyecto. Asegúrese de que su proyecto esté configurado para servir los archivos HTML estáticos:

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

A continuación, edite el archivo index.html en el nivel superior del directorio de Swagger UI dist . Hacia la parte superior del archivo, verá algunos JavaScript que se refieren a la URL de api-docs de otro proyecto. Edite esto para señalar la documentación de Swagger de su proyecto:

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

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

Answer 2

La interfaz de usuario de Springfox Swagger funciona para mí después de agregar la dependencia 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 {
 }

Answer 3

También puede considerar usar swagger-maven-plugin para generar swagger.json y copiarlo en el estático swagger-ui.

Verifique una muestra simple del complemento de trabajo con anotaciones Spring MVC en este repositorio:

https://github.com/khipis/swagger-maven-example

o para JAX-RS

https://github.com/kongchen/swagger-maven-example