Springfox (Swagger spec 2.0, güncel)
Springfox , Swagger-SpringMVC'nin yerini aldı ve artık hem Swagger teknik özellikleri 1.2 hem de 2.0'ı destekliyor. Uygulama sınıfları, biraz daha derin özelleştirmeye izin verecek şekilde, ancak biraz çalışmayla değişti. Dokümantasyon geliştirilmiş, ancak yine de gelişmiş yapılandırma için eklenen bazı ayrıntılar gerekiyor. 1.2 uygulaması için eski cevap hala aşağıda bulunabilir.
Maven bağımlılığı
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
Çıplak minimum uygulama aşağı yukarı aynı görünüyor, ancak artık Docketsınıf yerine SwaggerSpringMvcPluginsınıfı kullanıyor:
@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();
}
}
Swagger 2.0 API belgeleriniz şimdi adresinde mevcut olacak http://myapp/v2/api-docs.
Not: Spring boot kullanmıyorsanız, jackson-databind bağımlılığı eklemelisiniz. Springfox veri bağlama için Jackson kullandığından beri.
Swagger UI desteği eklemek artık çok daha kolay. Maven kullanıyorsanız, Swagger UI webjar için aşağıdaki bağımlılığı ekleyin:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
Spring Boot kullanıyorsanız, web uygulamanız otomatik olarak gerekli dosyaları almalı ve http://myapp/swagger-ui.html(eski adıyla :) konumunda kullanıcı arayüzünü göstermelidir http://myapp/springfox. Spring Boot kullanmıyorsanız, yuriy-tumakha'nın aşağıdaki cevapta bahsettiği gibi, dosyalar için bir kaynak işleyici kaydetmeniz gerekecektir. Java yapılandırması şuna benzer:
@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/");
}
}
Yeni statik belge oluşturma özelliği de oldukça hoş görünüyor, ancak bunu kendim denemedim.
Swagger-SpringMVC (Swagger spec 1.2, daha eski)
Swagger-SpringMVC'nin dokümantasyonu biraz kafa karıştırıcı olabilir, ancak aslında kurulumu inanılmaz derecede kolaydır. En basit yapılandırma, bir SpringSwaggerConfigfasulye oluşturmayı ve açıklama tabanlı yapılandırmayı etkinleştirmeyi gerektirir (muhtemelen Spring MVC projenizde zaten yapıyorsunuz):
<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
Bununla birlikte, SwaggerSpringMvcPluginönceki XML tanımlı çekirdek yerine özel bir Swagger yapılandırmasını tanımlamanın ekstra adımını atmaya değer olduğunu düşünüyorum :
@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();
}
}
Uygulamanızı çalıştırdığınızda, şimdi API spesifikasyonunuzun oluşturulduğunu görmelisiniz http://myapp/api-docs. Süslü Swagger UI kurulumunu elde etmek için, statik dosyaları GitHub projesinden klonlamanız ve bunları projenize yerleştirmeniz gerekir. Projenizin statik HTML dosyalarını sunacak şekilde yapılandırıldığından emin olun:
<mvc:resources mapping="*.html" location="/" />
Ardından index.htmldosyayı Swagger UI distdizininin üst seviyesinde düzenleyin . Dosyanın üst kısmına doğru, api-docsbaşka bir projenin URL'sine atıfta bulunan bazı JavaScript'ler göreceksiniz . Bunu, projenizin Swagger belgelerine işaret edecek şekilde düzenleyin:
if (url && url.length > 1) {
url = url[1];
} else {
url = "http://myapp/api-docs";
}
Şimdi adresine http://myapp/path/to/swagger/index.htmlgittiğinizde, projeniz için Swagger UI örneğini görmelisiniz.