Swagger --Api接口文档

Swagger简介

前后端分离

最常见的：Vue + SpringBoot

前后端分离，后台负责写接口。随着接口越来越多，随时改变接口的可能性也很大，大家争吵是很正常的。

解决方案

• 先指定计划提纲，事实更新API，降低集成风险
• 传统是需要自己去维护一个doc的文档或者公司统一放在一个接口清单的web服务上。每次开发者需要单独添加上去。修改后还需要维护。
• 前后端分离：
  • 前端测试后端接口：postman，就为了测一个接口还要下载第三方软件，太奢侈了
  • 后端提供接口，实时更新消息及变动

现接入swagger，通过简单的注解即可生成文档，并且随着接口变化自动会变化。统一管理方便快捷

Swagger

• 号称最流行的API框架
• RestFul Api 文档在线自动生产，Api文档与定义同步更新
• 直接运行，可以在线测试接口
• 支持多种语言（java、php等）

官网：https://swagger.io/

SpringBoot集成Swagger

1.新建SpringBoot项目
2.导入依赖

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

3.随便写一个controller接口，比如 hello
4.配置swagger2，swagger2 是新版的，和swagger 是不一样的哦！

/**
 * @author : aBiu---
 *
 * create at:  2019-12-20  16:20
 *
 * description: api接口配置
 */
@Configuration
@EnableSwagger2     // 开启
public class SwaggerConfig {
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("API接口文档") //页面标题
        .description("接口管理")//详细描述
        .version("1.0.0") //版本号
        .build();
  }
  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())     // 需要上面定义的ApiInfo，信息显示到页面上
        .groupName("aBiu")      // 分组，如果想搞多个分组，就写多个Docket 的示例就行了
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.*")) //这里写的是API接口所在的包位置，也可以设置其他扫描方式
        .paths(PathSelectors.any())     // 过滤，有好几种方式可以设置
        .build();
  }
}

5.测试运行，然后访问：http://localhost:8080/swagger-ui.html 或 http://localhost:8080/swagger-ui/index.html

由于版本的不同，可能名字不一样，具体可以到jar包里去看一下就好了

Swagger注解

@Api：　　　　　　　　　　修饰类，一般来描述Controller的
@ApiOperation：　　　　 描述类的 方法 或者 接口
@ApiParam：　　　　　　　单个参数描述
@ApiModel：　　　　　　　用在实体类上面
@ApiProperty：　　　　　实体类里面的属性
@ApiImplicitParam：      用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息               
　　　　　　　　　　　　　　　　name：参数名        
　　　　　　　　　　　　　　　　value：参数的汉字说明、解释        
　　　　　　　　　　　　　　　　required：参数是否必须传        
　　　　　　　　　　　　　　　　paramType：参数放在哪个地方            · 
　　　　　　　　　　　　　　　　header --> 请求参数的获取：@RequestHeader            · 
　　　　　　　　　　　　　　　　query --> 请求参数的获取：@RequestParam            · 
　　　　　　　　　　　　　　　　path（用于restful接口）--> 请求参数的获取：@PathVariable            · 
　　　　　　　　　　　　　　　　body（不常用）            · 
　　　　　　　　　　　　　　　　form（不常用）            
　　　　　　　　　　　　　　　　dataType：参数类型，默认String，其它值dataType="Integer"               
　　　　　　　　　　　　　　　　defaultValue：参数的默认值
　　　　　　　　　　　　　　　　其它若干

@ApiResponse：　　　　　描述HTTP响应其中1个的描述
@ApiResponses：　　　　 描述出HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit

示例：一个接口的说明（controller类）

/**
     * XXX 认证人员信息接口
     * @param signerType
     * @param certType
     * @param certNo
     * @param name
     * @param phoneNo
     * @param cardNo
     * @param signSupplier
     * @param authType
     * @param notifyUrl
     * @return
     */
    @ApiOperation(value = "XXX 的接口", httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "String", name = "signerType", dataType = "String", required = true, value = "签署人类型:1.个人，2.企业"),
            @ApiImplicitParam(paramType = "String", name = "certType", dataType = "String", required = false, value = "证件类型:签署人类型是个人时必填"),
            @ApiImplicitParam(paramType = "String", name = "certNo", dataType = "String", required = false, value = "签署人类型:签署人类型是个人时必填"),
            @ApiImplicitParam(paramType = "String", name = "name", dataType = "String", required = true, value = "姓名"),
            @ApiImplicitParam(paramType = "String", name = "phoneNo", dataType = "String", required = false, value = "手机号:签署人类型是个人时必填"),
            @ApiImplicitParam(paramType = "String", name = "notifyUrl", dataType = "String", required = false, value = "回调地址")
    })
    @PostMapping("/signerInfo")
    public ResultInfo signerInfo(String signerType, String certType, String certNo, String name, String phoneNo, @RequestParam(required = false) String notifyUrl){
        return xxxService.signerInfo(signerType,certType,certNo,name,phoneNo,cardNo,signSupplier,authType,notifyUrl);
    }

项目发布上线时候，一定要记得，一定要记得，把swagger 关闭，因为你不可能让用户看到你的接口吧？

生成漂亮的ui界面

加入依赖

    <dependency>
        <groupId>com.github.caspar-chen</groupId>
        <artifactId>swagger-ui-layer</artifactId>
        <version>1.1.3</version>
    </dependency>   

访问地址 http://localhost:8080/docs.html

这个好像没有分组的属性，如果swagger配置时候加了分组，在这里会有异常