swagger SpringBoot整合使用swagger2

Swagger2

在项目开发中，前后端都是通过接口文档进行沟通，而一个好的接口文档可以减少很多成本，但是在开发过程中，接口文档总是会出现各种的变化，例如，开始设计的文档不合理，或者甲方需求变更等，接口文档有变化就需要进行维护，而维护起来比较麻烦，很容易造成文档与代码不一致，所以我们可以使用swagger来让我们接口更规范，以及方标维护。

swagger是一个Redtful接口的文档自动生成，以及测试的软件（可以自动生成RestFul的接口文档以及对接口进行测试）

1. 引入依赖

   <!--Swagger2 依赖-->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-spring-web</artifactId>
       <version>2.9.2</version>
   </dependency>
   

2. 编写Swagger2的配置类

   @SpringBootConfiguration
   @EnableSwagger2  // 开启swagger注解的使用
   public class SpringSwagger2 {
       @Bean
       public Docket createRestApi(){
           return new Docket(DocumentationType.SWAGGER_2).pathMapping("/")
                   // 配置请求控制器的包
                   .select().apis(RequestHandlerSelectors.basePackage("com.zhiyou.controller"))
                   // 配置PathSelectors的路径 这里是扫描所有
                   .paths(PathSelectors.any())
                   // 构建一个Api描述信息 以及标题
                   .build().apiInfo(new ApiInfoBuilder().title("Swagger接口文档")
                   // Api 的总体描述信息
                   .description("Swagger接口文档描述，接口说明")
   
                   // Api 业务的url
                   .termsOfServiceUrl("http://localhost:8080/")
                   // 总体的版本号
                   .version("1.0.0").build());
       }
   
   }
   

   controller代码（示例）

   @RestController
   // tags 子标题,description 子描述
   @Api(tags = "测试用户相关接口",description = "用户接口的测试")
   public class TestController {
       @PostMapping("add")
       // ApiOperation 描述方法
       @ApiOperation(value = "value添加用户")
       public String add(User user){
           System.out.println(user);
           return "增加成功";
       }
       @DeleteMapping("delete")
       @ApiImplicitParam(name = "id",value = "用户的ID",defaultValue = "66")
       @ApiOperation(value = "value根据ID删除用户",notes = "notes根据ID删除用户")
       public String delete(int id){
           return "删除成功";
       }
       @PutMapping("update")
       @ApiImplicitParams({
               @ApiImplicitParam(name = "id",value = "用户的ID",defaultValue = "66",required = true),
               @ApiImplicitParam(name = "sex",value = "用户的性别",defaultValue = "男"),
               @ApiImplicitParam(name = "name",value = "用户的姓名",defaultValue = "憨憨"),
               @ApiImplicitParam(name = "money",value = "用户的金额",defaultValue = "2.2"),
       })
       @ApiOperation(value = "value修改用户",notes = "notes修改用户")
       public String update(String name,String sex,int id,double money){
           return "增加成功";
       }
       @GetMapping("find")
       @ApiImplicitParam(name = "id",value = "用户的ID")
       @ApiOperation(value = "value根据ID查询用户",notes = "notes根据ID查询用户")
       public String find(int id){
           return "查询成功";
       }
       // 这个方法不产生Api文档
       @ApiIgnore
       @GetMapping("find2")
       public String find2(int id){
           return "查询成功";
       }
   }
   

最后启动项目访问 http://loclahost:8080/swagger-ui.html 即可访问到对应的API文档

在文档中可以对对应的接口进行相关的测试

Swagger的注解：

注解	作用域	用途
@Api	类/接口	描述类和接口的用处
@ApiImplicitParam	方法	描述方法的非对象形参
@ApiImplicitParams	方法	描述方法的非对象形参
@ApiOperation	方法	描述方法的用处
@ApiIgnore	类/方法/形参	忽略相关的接口文档
@ApiModel	参数实体类	设置实体类的描述
@ApiModelProperty	实体类属性	实体类属性的描述

注意点：如果controller中的形参是对象,并且这个对象的model类中使用了@ApiModel注解的话,那么这个方法可以不使用@ApiImplicitParam注解来标识形参,swagger会自动使用model类中的描述来描述形参。