Springfox (Swagger spec 2.0, ปัจจุบัน)
Springfoxได้เข้ามาแทนที่ Swagger-SpringMVC และตอนนี้รองรับทั้งสเปค Swagger 1.2 และ 2.0 คลาสการใช้งานมีการเปลี่ยนแปลงทำให้สามารถปรับแต่งได้ลึกขึ้น แต่มีบางงาน เอกสารได้ดีขึ้น แต่ยังคงต้องการรายละเอียดบางอย่างเพิ่มสำหรับการกำหนดค่าขั้นสูง คำตอบเก่าสำหรับการใช้งาน 1.2 ยังคงอยู่ด้านล่าง
การพึ่งพา Maven
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
การใช้งานขั้นต่ำเปล่าดูเหมือนมากหรือน้อยเหมือนกัน แต่ตอนนี้ใช้Docketคลาสแทน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();
}
}
เอกสาร Swagger 2.0 API ของคุณจะอยู่ที่http://myapp/v2/api-docs.
หมายเหตุ: หากคุณไม่ได้ใช้ Spring boot คุณควรเพิ่มการพึ่งพาแจ็คสัน - ฐานข้อมูล เนื่องจาก springfox ใช้แจ็คสันสำหรับการเชื่อมต่อฐานข้อมูล
การเพิ่มการรองรับ Swagger UI นั้นง่ายยิ่งกว่าเดิม หากคุณใช้ Maven ให้เพิ่มการอ้างอิงต่อไปนี้สำหรับ Webjar Swagger UI:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
หากคุณกำลังใช้ Spring Boot แล้ว app เว็บของคุณควรเลือกโดยอัตโนมัติไฟล์ที่จำเป็นและแสดง UI ที่http://myapp/swagger-ui.html(ชื่อเดิม: http://myapp/springfox) หากคุณไม่ได้ใช้ Spring Boot ตามที่ yuriy-tumakha กล่าวไว้ในคำตอบด้านล่างคุณจะต้องลงทะเบียนตัวจัดการทรัพยากรสำหรับไฟล์ การกำหนดค่า Java มีลักษณะดังนี้:
@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/");
}
}
ใหม่รุ่นเอกสารคงคุณลักษณะที่ยังดูดีมาก แต่ผมไม่ได้พยายามออกเอง
Swagger-SpringMVC (Swagger spec 1.2 รุ่นเก่ากว่า)
เอกสารสำหรับSwagger-SpringMVCอาจทำให้สับสนเล็กน้อย แต่จริงๆแล้วการตั้งค่านั้นง่ายอย่างเหลือเชื่อ การกำหนดค่าที่ง่ายที่สุดต้องสร้างSpringSwaggerConfigbean และเปิดใช้งานการกำหนดค่าตามคำอธิบายประกอบ (ซึ่งคุณอาจทำในโครงการ Spring MVC ของคุณแล้ว):
<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
อย่างไรก็ตามฉันคิดว่ามันคุ้มค่าที่จะทำตามขั้นตอนพิเศษในการกำหนดคอนฟิกูเรชัน Swagger แบบกำหนดเองโดยใช้SwaggerSpringMvcPluginแทนถั่วที่กำหนดโดย 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.*");
}
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();
}
}
เมื่อคุณเรียกใช้โปรแกรมประยุกต์ของคุณตอนนี้คุณควรจะเห็นข้อมูลจำเพาะ API http://myapp/api-docsของคุณสร้างขึ้นที่ ในการตั้งค่า UI ของ Swagger ที่สวยงามคุณต้องโคลนไฟล์แบบคงที่จากโครงการ GitHubและใส่ไว้ในโครงการของคุณ ตรวจสอบให้แน่ใจว่าโครงการของคุณได้รับการกำหนดค่าให้แสดงไฟล์ HTML แบบคงที่:
<mvc:resources mapping="*.html" location="/" />
จากนั้นแก้ไขindex.htmlไฟล์ที่ระดับบนสุดของdistไดเร็กทอรีSwagger UI ที่ด้านบนสุดของไฟล์คุณจะเห็น JavaScript ที่อ้างถึงapi-docsURL ของโปรเจ็กต์อื่น แก้ไขสิ่งนี้เพื่อชี้ไปที่เอกสาร Swagger ของโครงการของคุณ:
if (url && url.length > 1) {
url = url[1];
} else {
url = "http://myapp/api-docs";
}
ตอนนี้เมื่อคุณไปที่http://myapp/path/to/swagger/index.htmlคุณจะเห็นอินสแตนซ์ Swagger UI สำหรับโครงการของคุณ