Uma maneira 'simples' de implementar Swagger em um aplicativo Spring MVC

Eu tenho uma API ReSTFul escrita em Spring simples (sem Spring Boot, sem coisas sofisticadas!). Eu preciso implementar o Swagger nisso. Até agora, CADA página na internet só me deixou louco com configurações confusas e código inchado que eu não achei portátil.

Alguém tem um projeto de amostra (ou um conjunto de etapas detalhadas) que pode me ajudar a realizar isso? Em particular, estou procurando um bom exemplo que usa swagger-springmvc. Eu sei que tem 'amostras', mas na melhor das hipóteses, o código esotérico é desanimador.

Devo esclarecer que não estou procurando "por que Swagger é simplesmente o melhor". Não estou usando (e para minha tarefa atual não vou usar) Spring Boot ou algo semelhante.

Springfox (Swagger spec 2.0, atual)

Springfox substituiu Swagger-SpringMVC e agora oferece suporte às especificações Swagger 1.2 e 2.0. As classes de implementação mudaram, permitindo uma personalização mais profunda, mas com algum trabalho. A documentação melhorou, mas ainda precisa de alguns detalhes adicionados para configuração avançada. A resposta antiga para a implementação 1.2 ainda pode ser encontrada abaixo.

Dependência Maven

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

A implementação mínima parece mais ou menos a mesma, mas agora usa a Docketclasse em vez da SwaggerSpringMvcPluginclasse:

@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();
    }

}

Sua documentação da API do Swagger 2.0 agora estará disponível em http://myapp/v2/api-docs.

Nota: Se você não estiver usando o Spring boot, deverá adicionar a dependência jackson-databind. Já que springfox usa jackson para ligação de dados.

Adicionar suporte para Swagger UI é ainda mais fácil agora. Se você estiver usando o Maven, adicione a seguinte dependência para o webjar da IU do Swagger:

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

Se você estiver usando Spring Boot, seu aplicativo da web deve selecionar automaticamente os arquivos necessários e mostrar a IU em http://myapp/swagger-ui.html(anteriormente:) http://myapp/springfox. Se você não estiver usando o Spring Boot, como yuriy-tumakha menciona na resposta abaixo, você precisará registrar um manipulador de recursos para os arquivos. A configuração Java é semelhante a esta:

@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/");
    }

}

O novo recurso de geração de documentação estática também parece muito bom, embora eu não tenha experimentado sozinho.

Swagger-SpringMVC (Swagger spec 1.2, mais antigo)

A documentação do Swagger-SpringMVC pode ser um pouco confusa, mas na verdade é incrivelmente fácil de configurar. A configuração mais simples requer a criação de um SpringSwaggerConfigbean e a ativação da configuração baseada em anotação (o que você provavelmente já faz em seu projeto Spring MVC):

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

No entanto, acho que vale a pena dar o passo extra de definir uma configuração personalizada do Swagger usando o SwaggerSpringMvcPlugin, em vez do bean definido em XML anterior:

@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();
    }

}

Ao executar seu aplicativo, você deve ver a especificação da API criada em http://myapp/api-docs. Para configurar a interface do Swagger, você precisa clonar os arquivos estáticos do projeto GitHub e colocá-los em seu projeto. Certifique-se de que seu projeto esteja configurado para servir os arquivos HTML estáticos:

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

Em seguida, edite o index.htmlarquivo no nível superior do distdiretório Swagger UI . No início do arquivo, você verá um pouco de JavaScript que se refere à api-docsURL de outro projeto. Edite para apontar para a documentação Swagger do seu projeto:

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

Agora, quando você navegar para http://myapp/path/to/swagger/index.html, deverá ver a instância de IU do Swagger para seu projeto.

Springfox Swagger UI funciona para mim depois de adicionar dependências WebJar e mapeamentos 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/"/>

ou Spring Annotation https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java

Swagger2 deve ser habilitado

 @EnableSwagger2
 public class SwaggerConfiguration {
 }

Você também pode considerar o uso do plug-in swagger-maven para gerar swagger.json e copiá-lo para o seu swagger-ui estático.

Verifique um exemplo simples de plug-in funcional com anotações Spring MVC neste repositório:

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

ou para JAX-RS

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