Spring Boot跟Swagger2整合，自动生成接口文档

在这之前，公司的api文档都是自己编写管理的，有些麻烦。所以最近经理就叫我看看这个Swagger，作为一个小白，就参考了别人的写了个Demo，这里稍微记录下。

一、 准备Spring Boot的项目

方式有很多，eclipse中可以使用插件 sts ，或者也可以直接访问 https://start.spring.io/，下载下来的是个压缩包，解压后导入开发工具即可。

二、引入依赖
这里用的是2.6.1的版本，Spring Boot用的是2.1.7版本

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.6.1</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.6.1</version>
</dependency>

三、编写配置类

@Configuration
public class SwaggerConfig {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))  //①
//				.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))  //②
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("swagger2构建api文档")
				.description("使用swagger2简单构建生成api文档的demo")
				.version("1.0")
				.build();
	}
	
}

①这是扫描带有Api注解的类
②这句就是根据指定的包路径来扫描

四、编写Controller接口

@Api(tags="UserController",description="用户管理接口")
@RequestMapping(value="/user")
@Controller
@ResponseBody
public class UserController {

	@ApiOperation(value="单条查询", notes="根据id查询用户信息")
	@ApiImplicitParam(name="id",value="用户id",dataType="Integer",paramType="path",required=true)
	@GetMapping(value="/getUser/{id}")
	public User getUserById(@PathVariable(value="id")Integer id) {
		
		User u = new  User();
		u.setId(id);
		u.setName("想是是");
		
		return u;
	}
	
	@ApiOperation(value="查询所有")
	@GetMapping(value="/findUsers")
	public List<User> findUsers(){
		
		User u = new User(1,"小黑");
		User u2 = new User(2,"兰兰");
		
		List<User> users = new ArrayList<>();
		users.add(u2);
		users.add(u2);
		return users;
		
	}
	
}

这里就简单写点好了，我的目的是能生成接口文档就好~~

实体User.class

public class User {
	
	private Integer id;
	private String name;
	
	// Getter Setter
}

以上完成后就可以启动项目，然后访问 http://localhost:8080/swagger-ui.html
（该地址就是你项目的 ip:端口/(可能有项目名)/swagger-ui.html）

更多可参考：spring-boot-swagger2 使用手册
相关注解说明：

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

以上，就完成了！！

可能遇到的问题

可能在整合其他项目时会有页面找不到 404 错误的问题，那就是该静态页面被拦截了，需要放开。
（继承 WebMvcConfigurationSupport）

@Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

好了，写的有点久了，该溜了~~~~（以上内容均来自参考）