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.*");
}
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.