现如今，前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，

但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，Swagger2 就可以很好地解决，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。

有时候定义了文档，代码中修改了一点小的东西，总会忘记同步修改文档，时间长了，自己都比较蒙，还需要看一下代码才能发现问题。

1. swagger整合步骤

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格
式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。
（https://github.com/OAI/OpenAPI-Specification）
Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周
期的开发。 (https://swagger.io/)
Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建
项目的框架

1.1. 引入swagger依赖

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

1.2. 在主程序类名上使用@EnableSwagger注解启用

@EnableSwagger2
@SpringBootApplication
public class EncryptcaseApplication {

    public static void main(String[] args) {
        SpringApplication.run(EncryptcaseApplication.class, args);
    }

}

1.3. 启动项目 访问swagger首页

2. swagger的基础注解介绍

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

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

2.2. 代码中添加swagger注解

@Api(tags = "用户模块")
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    UserService userService;
    @ApiOperation(value ="查询指定id的用户" )
    @ApiImplicitParams(
            value = {
                    @ApiImplicitParam(name = "id",required = true,defaultValue ="1001",dataType = "int"),
                    @ApiImplicitParam(name="name",required = false,defaultValue = "小华",dataType = "String")
            }
    )
    @ApiResponses(value = {
            @ApiResponse(code = 10001 , message = "查询失败" ),
            @ApiResponse(code = 10002 , message = "数据库连接失败" ),
            @ApiResponse(code = 10003 , message = "查询超时" )

    })
    @GetMapping("/getUser")
    public User getUser(Integer id,String name){
        // name参数是测试swagger加的
        return userService.getUser(id);
    }
    @ApiOperation(value ="查询用户和电影信息的")
    @ApiImplicitParam(name="id",defaultValue = "1200",required = true)
    @GetMapping("/getUserAndMovie")
    public Map getUserAndMovie(Integer id){
        return userService.getUserAndMovie(id);
    }

}

2.3. 实体类接口文档

在controller中用到的实体类

2.4.模块分组

@Configuration
@EnableSwagger2 //启用swagger功能
public class SwaggerConfig {
    //ApiInfo swagger接口文档整体的描述
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("电影系统接口文档").description("提供用户模块/权限模块/管理员模块的文档")
                .termsOfServiceUrl("http://www.atguigu.com/").version("1.0").build();
    }
    //  一个Docket代表接口文档中的一个分组
    @Bean("用户模块")
    public Docket userApis() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("用户模块").select()
                .apis(RequestHandlerSelectors.basePackage("com.atguigu.nacos.controller.user")).paths(PathSelectors.any())
                .build().apiInfo(apiInfo()).enable(true);
    }
    @Bean("认证模块")
    public Docket authApis() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("认证模块").select()
                .apis(RequestHandlerSelectors.basePackage("com.atguigu.nacos.controller.auth")).paths(PathSelectors.any())
                .build().apiInfo(apiInfo()).enable(true);
    }
    @Bean("所有模块")
    public Docket allApis() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("所有模块").select()
                .apis(RequestHandlerSelectors.basePackage("com.atguigu.nacos.controller")).paths(PathSelectors.any())
                .build().apiInfo(apiInfo()).enable(true);
    }
}