初识Swagger

有关Swagger的学习

认识Swagger

Swagger是一个规范和完整的框架，用于生成、描述、调用可视化RESTFul风格的Web服务。总体的目标是使客户端和文件系统作为服务器以同样的速度进行更新。文件的方法、参数和模型紧密集成到服务器端的代码中，允许API来始终保持同步。

作用

1.接口文档的在线生成
2.方便接口写好之后功能的测试

Maven依赖

版本号可以根据自己实际的需要进行相应的修改，对于Swagger来说，主要应用的是springfox-swagger2和springfox-swagger-ui依赖。maven以来如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox-swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox-swagger.version}</version>
</dependency>

创建Swagger配置信息类

原则上：建议将Swagger.java类与application.java类保持同级，配置信息如下：

//在该与SpringBoot集成的时候，放在与application.java同级的目录下，下面分别解释两个注解的作用与意义
//Configuration ：让Spring来加载该类的配置信息
//EnableSwagger2 ：进行开启Swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig{

    /**
     * @Description：创建该API的基本信息（这些信息将会展示在文档的界面）
   		文档的访问地址： http://项目实际地址/swagger-ui.html
     * @Author: Xzy
     * @Date: 19:07 2020/9/1
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("SpringBoot中使用Swagger2构建RESTful APIs")
                .description("该接口主要是针对xxx项目的接口信息")
                .termsOfServiceUrl("Hello World")
                .contact("Xzy") //指明创建的作者
                .version("1.0")
                .build();
    }


    /**
     * @Description：
        TODO 该方法主要是用来创建Api应用，下面分别介绍类中的各个方法的作用
            apiInfo()  增加API相关的信息
            select()  返回的是一个ApiSelectorBuilder实例，用来控制哪些接口暴露给Swagger来进行展现，
                        本例采用的是通过扫描包路径指定要建立API的目录
     * @Author: Xzy
     * @Date: 16:39 2020/9/1
    */
    @Bean
    public Docket createRestApi(){
      return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.cn.zzmj.controller"))  //用来确定暴露给Swagger哪些接口，通过包路径的扫描
            .paths(PathSelectors.any())
            .build();
    }
    
}

通过以上代码，通过createApi()方法创建Docket的Bean之后，apiInfo()用来创建该Api在界面中实现的基本信息。

接口

在完成上述对Swagger的基本配置信息之后，其实已经可以访问以及查看响应的文档内容，但是这样生成的文档只是针对我们服务器请求本身，对用户来说并不友好，我们需要添加一些说明来丰富文档的信息。

Swagger常用注解

@Api: 用在类上，说明该类的主要作用；
@ApiOperation: 注解用来给API增加方法说明；
@ApiImplicitParam: 注解用来给方法入参增加说明

使用如下：

@Api(value = "该注解是作用在类上，说明该类的作用")
@RestController
@RequestMapping("/test")
public class TestController {

    /**
     * @Description：该方法主要是用来测试接口是否可用
     * @Author: Xzy
     * @Date: 16:24 2020/6/30
    */

    @GetMapping("/getAllTestData")
    @ApiOperation(value = "该注解作用在方法上，主要针对的是解释该方法的作用",notes = "进一步解释方法的细节")
    //TODO paramType  主要的值为：
    // header（请求参数放置于RequestHeader 使用@RequestHeader来获取）
    // query(请求参数放置于请求地址，使用@RequestParam来进行获取)
    // path(用于restful接口  请求参数的获取：@PathVariable)
    // body（不常用）、form（不常用）

    @ApiImplicitParam(paramType = "query",name = "userName",dataType = "String",required = true,value = "用户的姓名")
    public List<Object> getAllTestData(@RequestParam String userName){
        System.out.println(userName);
        List<Object> list = new ArrayList<>();
        list.add(JSON.toJSON("小明"));
        list.add(JSON.toJSON("小明1"));
        list.add(JSON.toJSON("小明2"));
        list.add(JSON.toJSON("小明3"));
        list.add(JSON.toJSON("小明4"));
        list.add(JSON.toJSON("小明5"));
        return list;
    }

}

显示

两个注意点

1.paramType：会直接影响到程序的运行期，如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收；
2.Controller中的方法需要指明是哪种方法类型，否则Swagger默认使全类型均可以进行访问，API条目中会生成多条数据接口。

参考

该文档参考的是：

> Swagger使用指南_sanyaoxu_3的博客-CSDN博客_swagger