接口文档生成工具Swagger2的使用

1、什么是Swagger

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

　　做用：

　　1. 接口的文档在线自动生成。

　　2. 功能测试。

2、在Maven中添加依赖

　　

<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>

3、建立Swagger2的配置类

　　

/** * Swagger2 配置类 * 在与spring boot 集成时，放在与application.java 同级的目录下 * 经过@Configuration注解，让spring来加载该配置 * 再经过@EnableSwagger2注解来启动Swagger2 */ @Configuration @EnableSwagger2 public class Swagger2 { /** * 建立API应用 * appinfo()增长API相关信息 * 经过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给Swagger来展示 * 本例采用置顶扫描的包路径来定义指定要创建API的目录 * * @return
     */ @Bean public Docket createRestApi() { Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.shuke.chat")) .paths(PathSelectors.any()).build(); return docket; } /** * 建立改API的基本信息（这些基本信息会展现在文档页面中） * 访问地址： http://项目实际地址/swagger-ui.html * @return
     */
    public ApiInfo apiInfo() { return new ApiInfoBuilder() .title("使用websocket实现实时通信 APIs") .description("了解更多请联系：shuke") .termsOfServiceUrl("http://www.baidu.com") .contact("shuke") .version("1.0") .build(); } }

4、Swagger2 的注解使用

　　

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

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

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

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

@ApiResponses：用于表示一组响应

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

    *  code：数字，例如400

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

    *  response：抛出异常的类   

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

    *  @ApiModelProperty：描述一个model的属性

 

注意：@ApiImplicitParam的参数说明：

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

 

/** * @author shuke * @date 2018/10/16 */ @Api("ChatInfoController|图片和音频上传控制器类") @RestController public class ChatInfoController { /** * 上传图片接口 * @param attach 文件对象 * @param request http请求 * @return imgSrc：上传后图片文件的路径 */ @ApiOperation(value = "上传图片",notes = "文件不能超过20M大小，后缀名为png，jpg，gif") @RequestMapping(value = "/uploadImg",method = RequestMethod.POST) @ResponseBody public String uploadImg(@RequestParam("file") MultipartFile attach,HttpServletRequest request) { System.out.println("上传图片"); return FileUp.upFile(attach, request, Constants.IMAGE, true); } /** * 上传语音接口 * @param attach 文件对象 * @param request http请求 * @return audioSrc:上传后语音文件的路径 */ @ApiOperation(value = "上传语音",notes = "文件不能超过20M大小，后缀名为MP3，silk，flv") @RequestMapping(value = "/uploadAudio",method = RequestMethod.POST) @ResponseBody public String uploadAudio( @RequestParam("file") MultipartFile attach,HttpServletRequest request) { System.out.println("上传语音"); return FileUp.upFile(attach, request, Constants.AUDIO, true); } }

添加注解后启动springboot，输入http://localhost:8080/swagger-ui.html便可进入文档页面