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 请求，得到返回值：
