Swagger

一、为什么要使用swagger

在前后端分离的时代，前端人员和后端人员无法做到“及时协商，尽早解决”，最终会导致许多的问题出现。
解决方案：

• 首先制定一个schema，实时更新最新的API，降低集成的风险；
• 前后端分离
  • 前端测试后端接口：postman
  • 后端提供接口，需要实时更新最新的消息及改动
    这里可以参考swagger的官网 https://swagger.io/

二、springboot集成swagger

这里是以springboot 2.6.0和swagger3.0.0版本作为演示

首先在pom.xml文档里面加入这个依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

然后需要写一个对于swagger的配置类

@Configuration
@EnableOpenApi
@EnableWebMvc
public class SwaggerConfig {

    //分组
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }


    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }


    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

    @Bean
    public Docket docket(){


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)//默认为true 关闭后，则不能使用swagger
                .select()
                //指定接口的位置
                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                //过滤什么路径
                //.paths()
                .build();
                //.globalOperationParameters(pars);

    }

    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("William","https://mercurys-52hz.gitee.io/","chening_william@163.com");

        return new ApiInfo(
                "William的接口文档",
                "前端根据接口进行测试",
                "1.0",
                "https://mercurys-52hz.gitee.io/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

三、配置详解

1.swagger配置

在swagger3.0.0版本中，需要在配置类的上面加上 @EnableOpenApi，当然还有配置类需要的@Configuration注解，最重要的就是一定需要加上 @EnableWebMvc注解，不然控制面板就会报错，就是这个错误浪费了我一下午的时间

可以通过设置 .apis(RequestHandlerSelectors.basePackage(“com.swagger.controller”)) 里面的参数用来指定需要扫描的包，这里面还可以设置更多的参数，详情可以参照上面的这张图片。加上 paths() 后可以在里面设置过滤的路径不扫描。

2.信息配置

  private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("William","https://mercurys-52hz.gitee.io/","chening_william@163.com");

        return new ApiInfo(
                "William的接口文档",
                "前端根据接口进行测试",
                "1.0",
                "https://mercurys-52hz.gitee.io/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

这里主要就是配置一些作者的信息的名字好联系啥的，不太重要，就不细讲了。

3.配置多api分组

//分组
   @Bean
   public Docket docket1(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("A");
   }


   @Bean
   public Docket docket2(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("B");
   }


   @Bean
   public Docket docket3(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("C");
   }

作用就是为每个api分一下组。作用效果如下图

4.通过注解配置注释

凭空传过去，前端一定会一脸懵逼的，这时候就需要注释来帮助理解了。

四、swagger的使用

1、访问

swagger3.0的默认的访问地址为 主机地址+/swagger-ui/index.html

2、注释的使用

Swagger使用的注解及其说明：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

   code：数字，例如400

   message：信息，例如"请求参数没填好"

   response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

  @ApiModelProperty：描述一个model的属性

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）–>请求参数的获取：@PathVariable body：（不常用） form（不常用
name：参数名
dataType：参数类型
required：参数是否必须传	true / false
value：说明参数的意思
defaultValue：参数的默认值

示例:

@RestController
@Api("登录控制器")
public class loginController {


    @Autowired
    private UserService userService;


    @RequestMapping("/login")
    @ApiOperation("输入用户的id和密码，查询用户信息，如果数据库没有或者密码不对应则会返回空值")
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query",name = "id",value = "用户的id",required = true,dataType = "Integer",dataTypeClass = Integer.class,example = "123"),
                         @ApiImplicitParam(paramType = "query",name = "password", value = "密码",required = true,dataType = "String",dataTypeClass = String.class)
    })
    public User login(@RequestParam("id")int id, @RequestParam("password") String password){

        User loginuser = userService.doLogin(id,password);

        if(loginuser == null){
            return null;
        }else{
            return loginuser;
        }
    }

}

这里补充一点，在使用swagger(version 3.0)的进行上传文件的调试的时候需要注意一点，记得把把参数那里的文件的注解换一下，才能使swagger显示出来上传文件的按钮

@RequestPart("file") MultipartFile file

<<<<<完结撒花>>>>>