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

Posted taotao19131

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了接口文档生成工具Swagger2的使用相关的知识,希望对你有一定的参考价值。

一、什么是Swagger

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

  作用

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

  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>

三、创建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即可进入文档页面

技术分享图片

 

以上是关于接口文档生成工具Swagger2的使用的主要内容,如果未能解决你的问题,请参考以下文章

Swagger2--自动生成接口文档工具学习

SpringBoot之Swagger2文档生成

Swagger2 常用使用 及 SpringBoo 整合 Swagger2

springboot2.0入门--swagger2接口API构建

SpringBoot集成Swagger2生成API接口文档

SpringBoot集成Swagger2生成API接口文档