SpringBoot入门系列（五）——集成swagger

很多时候我们需要一个统一的文档管理器来管理我们的参数、控制器等部分，而swagger恰好提供了这些重要的功能
需要事先说明的是，swagger是侵入式开发，也就是说，使用swagger，需要修改原本的代码结构。在实际开发中，需要根据具体的项目情况做出取舍

第一步，配置dependency

<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.0.6.RELEASE</version>
	</parent>
	<groupId>com.xu</groupId>
	<artifactId>test-swagger</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<dependencies>
		<!-- 热部署工具 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-thymeleaf</artifactId>
		</dependency>
		<!-- swagger -->
		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>


		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>

	</dependencies>

	<!-- 热部署插件 -->
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<fork>true</fork>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

第二步，写配置文件

#Yaml的写法
debug: true
spring:
  devtools:
    restart:
      enabled: true  #设置开启热部署
  freemarker:
    cache: false    #页面不加载缓存，修改即时生效
swagger:
  enabled: true

光有YML还不够，还需要一个java类来读取配置，写法如下

package xu.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	@Value("${swagger.enabled}")
	private boolean enableSwagger;
	
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.enable(enableSwagger)
				.select()
				.apis(RequestHandlerSelectors.basePackage("xu.controller"))
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("测试swagger")
				.description("接口说明")
				.termsOfServiceUrl("http://localhost:8080/")
				.contact(new Contact("xu", "http://localhost:8080/", "3352336739@qq.com"))
				.version("1.0.0")
				.build();
	}
}

第三步，在控制器中使用Api

package xu.controller;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import xu.entity.User;

@RestController
@RequestMapping("/main")
@Api(value="restful接口测试",tags="RestFulController",description="测试接口")
public class LoginController {

	@PostMapping("/login")
	@ApiOperation(value="用户登录",notes="用户登录")
	public String logCon(@ApiParam(required=true,name="user",value="用户实体")User user) {
		if(user.getUserName().equals("xu") && user.getPassWord().equals("123")) {
			return "success";
		}
		return "error";
	}
}

可以看到，我们在控制器上加入了@Api注解，这个部分是将该控制器交给swagger管理，接下来到了具体方法时，用@PostMapping取代@RequestMapping，用@ApiOperation来对方法的功能进行描述。接收参数时，也不再使用@RequestBody，而是换成了@ApiParam。这里我们明显可以感觉到“侵入式开发”的痕迹

到这里后台已经全部写完了，如果想要查看效果，则需要在所访问的地址后面加上swagger-ui.html，即：http://localhost:8080/swagger-ui.html
效果如下：