Spring Boot系列十九 Spring boot集成 swagger

快来打我* 2022-05-23 11:25 266阅读 0赞

## Swagger简述 ##

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件  
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步

## Spring Boot集成Swagger ##

**本文涉及的工程**： swagger

**pom.xml**  
swagger需要引入如下的jar

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

**@EnableSwagger2**  
使用@EnableSwagger2注解在Control类上就可以swagger的功能

@RestController
    @EnableSwagger2 // 启动swagger注解
    // api-value：定义名称，如果没有定义，则默认显示类名
    @Api(value = "Swagger Test Control", description = "演示Swagger用法的Control类", tags = "Swagger Test Control Tag")
    public class SwaggerTestCtl { 
    ..
    }

**执行启动类**  
执行启动类，访问如下连接  
[http://127.0.0.1:8080/swagger-ui.html\#/][http_127.0.0.1_8080_swagger-ui.html]  
就可以进入swagger页面，进行接口测试，界面如下:  
![这里写图片描述][70]

## ApiInfo类 ##

我们创建ApiInfo实例，我们为swagger配置更多的接口说明

@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(getApiInfo())
            // .pathMapping("/")// base，最终调用接口后会和paths拼接在一起
            .select()
            // .paths(Predicates.or(PathSelectors.regex("/api/.*")))//过滤的接口
            .apis(RequestHandlerSelectors.basePackage("com.hry.swagger.ctl")) //过滤的接口
            .paths(PathSelectors.any())
            .build();
    }
    
    private ApiInfo getApiInfo() {
        // 定义联系人信息
        Contact contact = new Contact("hryou0922","https://github.com/hryou0922", "hryou0922@126.com");
        return new ApiInfoBuilder()
            .title("演示 Swagger 的用法") // 标题
            .description("演示Swagger中各种注解的用法") // 描述信息
            .version("1.1.2") // //版本
            .license("Apache 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
            .contact(contact)
            .build();
    }

重启服务，界面如下：  
![这里写图片描述][70 1]

## swagger的注解 ##

### swagger的注解概述 ###

我们可以使用swagger定义更详细接口说明

@Api：用在类上，标志此类是Swagger资源
        value：接口说明
        tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息
    
    @ApiOperation：用在方法上，描述方法的作用
    
    @ApiImplicitParams：包装器：包含多个ApiImplicitParam对象列表
    
    @ApiImplicitParam：定义在@ApiImplicitParams注解中，定义单个参数详细信息
            ○ paramType：参数放在哪个地方
                § header-->请求参数的获取：@RequestHeader
                § query-->请求参数的获取：@RequestParam
                § path（用于restful接口）-->请求参数的获取：@PathVariable
                § body（以流的形式提交 仅支持POST）
                § form（以form表单的形式提交 仅支持POST）
            ○ name：参数名
            ○ dataType：参数的数据类型 只作为标志说明，并没有实际验证
                § Long
                § String
            ○ required：参数是否必须传
                § true
                § false
            ○ value：参数的意义
            ○ defaultValue：参数的默认值
    
    @ApiModel：描述一个Swagger Model的额外信息
        @ApiModel用在类上，表示对类进行说明，用于实体类中的参数接收说明
    
    @ApiModelProperty：在model类的属性添加属性说明
    
    @ApiParam：用于Controller中方法的参数说明
    
    @ApiResponses：包装器：包含多个ApiResponse对象列表
    
    @ApiResponse：定义在@ApiResponses注解中，一般用于描述一个错误的响应信息
            ○ code：错误码，例如400
            ○ message：信息，例如"请求参数没填好"
            ○ response：抛出异常的类
    
    @Authorization  Declares an authorization scheme to be used on a resource or an operation.
    
    @AuthorizationScope Describes an OAuth2 authorization scope.

## 演示使用注解demo ##

本节我们演示上节的注解如何使用

### @Api ###

用在类上，标志此类是Swagger资源，对接口更加详细说明

@RestController
    @EnableSwagger2 // 启动swagger注解
    @Api(value = "Swagger Test Control", description = "演示Swagger用法的Control类", tags = "Swagger Test Control Tag")
    public class SwaggerTestCtl { 
    
    }

结果如下:  
![这里写图片描述][70 2]

### @ApiOperation ###

用在方法上，描述方法的作用

// 方法的说明
    @ApiOperation(value = "根据id获取记录", response = Student.class)
    // 定义请求参数
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "String", name = "id", value = "主键", required = true) })
    public Student queryById(String id){
        System.out.println("queryById id = " + id);
        return new Student();
    }

结果如下:  
![这里写图片描述][70 3]

### @ApiImplicitParams 和 @ApiImplicitParam ###

// 定义请求参数
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "String", name = "id", value = "主键", required = true) })
    public Student queryById(String id){
       System.out.println("queryById id = " + id);
       return new Student();
    }

结果如下:  
![这里写图片描述][70 4]

### @ApiModel 和@ApiModelProperty ###

定义model类

@ApiModel( description = "学生")
    public class Student {
        @ApiModelProperty(value = "主键id")
        private String id;
        @ApiModelProperty(value = "名称", required = true)
        private String name;
        @ApiModelProperty(value = "年龄", required = true)
        private int age;
    …
    }

在方法使用

@RequestMapping(value = "/update", method = {RequestMethod.POST})
    // 方法说明
    @ApiOperation(value = "添加学生记录", notes="传递复杂对象DTO",produces = "application/json")
    public int update(@RequestBody Student student){
        System.out.println("update student = " + student);
        return 1;
    }

结果如下:  
![这里写图片描述][70 5]

### @ApiResponses和@ApiResponse ###

@RequestMapping(value = "/del", method = {RequestMethod.POST, RequestMethod.GET})
    // 方法说明
    @ApiOperation(value = "删除学生记录学生记录")
    // 定义返回值意义
    @ApiResponses({
            @ApiResponse(code = 400, message = "服务器内部异常"),
            @ApiResponse(code = 500, message = "权限不足") })
    public int del(int id){
        System.out.println("del id = " + id);
        return 1;
    }

结果如下:  
![这里写图片描述][70 6]

## 其它 ##

在测试过程中，可能出现界面内容没有被刷新，则可以使用 shift + F5 强制刷新

## 代码 ##

以上的详细的代码见下面 [github代码，请尽量使用tag v0.22，不要使用master，因为我不能保证master代码一直不变][github_tag v0.22_master_master]

[http_127.0.0.1_8080_swagger-ui.html]: http://127.0.0.1:8080/swagger-ui.html#/
[70]: /images/20220523/cedba25cc5304f4f945afb193d6f29e4.png
[70 1]: /images/20220523/6163e94a54114b7892d42c1eee8faadb.png
[70 2]: /images/20220523/719396dc60564c3a9d08008ac37a6752.png
[70 3]: /images/20220523/cf59f245ceef4490b0f05fe93d531bb9.png
[70 4]: /images/20220523/e2dbcaf256eb4606a0e9f6bd53cc6869.png
[70 5]: /images/20220523/02cceda8ada242a1978a175925e86987.png
[70 6]: /images/20220523/924d1f13ba4e4fb381af92ea575e9f64.png
[github_tag v0.22_master_master]: https://github.com/hryou0922/spring_boot/tree/v0.22/swagger/src/main/java/com/hry/swagger