Swagger的用法

返回主页桃月伊人
博客园首页新随笔联系管理订阅订阅随笔 - 1 文章 - 0 评论 - 0
接口文档生成工具Swagger2的使用
一、什么是Swagger
　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

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

2. 功能测试。

二、在Maven中添加依赖

复制代码

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.2.2</version>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.2.2</version>

复制代码 三、创建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();
    }
    }
    复制代码
    四、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即可进入文档页面

当然这个端口和ip后期在实际项目的使用在配置自己的项目ip+端口+项目名+swagger-ui.html就可以了