Swagger的用法

柔光的暖阳◎ 2023-06-08 06:38 4阅读 0赞

返回主页桃月伊人  
博客园首页新随笔联系管理订阅订阅随笔 - 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就可以了