Springfox (Swagger spec 2.0, hiện tại)
Springfox đã thay thế Swagger-SpringMVC và hiện hỗ trợ cả thông số kỹ thuật Swagger 1.2 và 2.0. Các lớp triển khai đã thay đổi, cho phép một số tùy chỉnh sâu hơn, nhưng với một số công việc. Các tài liệu đã được cải thiện, nhưng vẫn cần một số chi tiết bổ sung cho cấu hình tiên tiến. Câu trả lời cũ cho việc triển khai 1.2 vẫn có thể được tìm thấy bên dưới.
Maven phụ thuộc
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
Việc triển khai tối thiểu gần như giống nhau, nhưng bây giờ sử dụng Docketlớp thay vì SwaggerSpringMvcPluginlớp:
@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();
}
}
Tài liệu API Swagger 2.0 của bạn hiện sẽ có sẵn tại http://myapp/v2/api-docs.
Lưu ý: Nếu bạn không sử dụng Spring boot thì bạn nên thêm phụ thuộc jackson-databind. Vì springfox sử dụng jackson cho databinding.
Giờ đây, việc thêm hỗ trợ giao diện người dùng Swagger thậm chí còn dễ dàng hơn. Nếu bạn đang sử dụng Maven, hãy thêm phần phụ thuộc sau cho webjar giao diện người dùng Swagger:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
Nếu bạn đang sử dụng Spring Boot, thì ứng dụng web của bạn sẽ tự động chọn các tệp cần thiết và hiển thị giao diện người dùng tại http://myapp/swagger-ui.html(trước đây http://myapp/springfox:). Nếu bạn không sử dụng Spring Boot, thì như yuriy-tumakha đề cập trong câu trả lời bên dưới, bạn sẽ cần đăng ký một trình xử lý tài nguyên cho các tệp. Cấu hình Java trông như thế này:
@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/");
}
}
Tính năng tạo tài liệu tĩnh mới trông cũng khá đẹp, mặc dù tôi chưa tự mình thử.
Swagger-SpringMVC (Swagger spec 1.2, cũ hơn)
Tài liệu cho Swagger-SpringMVC có thể hơi khó hiểu, nhưng nó thực sự rất dễ thiết lập. Cấu hình đơn giản nhất yêu cầu tạoSpringSwaggerConfig bean và bật cấu hình dựa trên chú thích (mà bạn có thể đã thực hiện trong dự án Spring MVC của mình):
<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
Tuy nhiên, tôi nghĩ rằng rất đáng để thực hiện thêm bước xác định cấu hình Swagger tùy chỉnh bằng cách sử dụng SwaggerSpringMvcPluginbean được định nghĩa bằng XML trước đó:
@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();
}
}
Khi bạn chạy ứng dụng của mình, bây giờ bạn sẽ thấy thông số API của mình được tạo tại http://myapp/api-docs. Để thiết lập giao diện người dùng Swagger ưa thích, bạn cần sao chép các tệp tĩnh từ dự án GitHub và đưa chúng vào dự án của mình. Đảm bảo rằng dự án của bạn được định cấu hình để phân phát các tệp HTML tĩnh:
<mvc:resources mapping="*.html" location="/" />
Sau đó, chỉnh sửa index.htmltệp ở cấp cao nhất của thư mục Swagger UI dist. Ở phía trên cùng của tệp, bạn sẽ thấy một số JavaScript đề cập đến api-docsURL của một dự án khác. Chỉnh sửa điều này để trỏ đến tài liệu Swagger của dự án của bạn:
if (url && url.length > 1) {
url = url[1];
} else {
url = "http://myapp/api-docs";
}
Bây giờ khi bạn điều hướng đến http://myapp/path/to/swagger/index.html, bạn sẽ thấy phiên bản giao diện người dùng Swagger cho dự án của mình.