Swagger for Spring Boot
Swagger 可用於生成、描述、調用和可視化 RESTful 風格接口的API，是一套規範和完整的開發框架，並且能對接口進行單獨測試。
Spring Boot 是目前對 Swagger 支持最好的框架，只需要引入 springfox-swagger 相關依賴：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
並在代碼中做如下配置：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jake.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("PROJECT API MANAGEMENT")
.description("項目 API 管理")
.contact(contact())
.version("1.0")
.build();
}
private Contact contact() {
return new Contact("Jake Weng", "https://blog.csdn.net/qq_15329947", "[email protected]");
}
}
本地啓動項目，在項目根路徑之後加入 swagger-ui.html 即可訪問，如 localhost:8080/swagger-ui.html
Swagger for Spring MVC
如果項目是基於 Spring MVC 框架的，那麼配置會相對複雜一些。
首先在 pom 中引入 Spring 和 Springfox 相關依賴：
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>${spring.framework.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>${spring.framework.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>${spring.framework.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox.swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox.swagger.version}</version>
</dependency>
首先，在 src / main / java 中新建 com.jake.demo.config 包，並在其中新建 SwaggerConfig.java，在其中加入：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jake.demo.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SWAGGER API MANAGEMENT")
.description("基於 Spring MVC 的 Swagger API 管理")
.contact(contact())
.version("1.0")
.build();
}
private Contact contact() {
return new Contact("Jake Weng", "https://blog.csdn.net/qq_15329947", "[email protected]");
}
}
在 webapp 中新建 WEB-INF / web.xml 文件，並在其中加入以下內容：
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
id="WebApp_ID" version="3.0">
<display-name>spring-mvc-swagger</display-name>
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:applicationContext.xml</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<servlet>
<servlet-name>dispatcherServlet</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath*:spring-mvc.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<filter>
<filter-name>encodingFilter</filter-name>
<filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
<init-param>
<param-name>forceEncoding</param-name>
<param-value>true</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>encodingFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<servlet-mapping>
<servlet-name>dispatcherServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
在 src / main / resources 資源類型文件夾下新建 applicationContext.xml 和 spring-mvc.xml。
在 applicationContext.xml 中寫入：
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:component-scan base-package="com.jake.demo"/>
<context:annotation-config/>
<bean class="com.jake.demo.config.SwaggerConfig"/>
</beans>
在 spring-mvc.xml 中加入：
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc.xsd">
<context:component-scan base-package="com.jake.demo.controller, com.jake.demo.config"/>
<mvc:annotation-driven>
<mvc:message-converters>
<bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter">
<property name="objectMapper">
<bean class="com.fasterxml.jackson.databind.ObjectMapper">
</bean>
</property>
</bean>
</mvc:message-converters>
</mvc:annotation-driven>
</beans>
在 IntelliJ IDEA 中配置好 Local Tomcat：
並在 IDEA 中啓動 Tomcat，待啓動成功後訪問 localhost:8080/swagger-ui.html，出現如下頁面：
點擊 Controller 可以查看並測試基於不同 HTTP 方法的 API，點擊 Models 可以查看 Java 的 View Object 類以及其中字段。
在 Controller 的 API 處，點擊 Try it out → execute 還可以向接口發起 HTTP 請求，得到返回值：
