Swagger的用法以及常用注解解释

﹏ヽ暗。殇╰゛Y 2023-10-18 23:37 93阅读 0赞

**目录**

1、首先添加Swagger的依赖

2、在接在类名以及方法上面添加对应的注解

3、演示代码

实体类的注解

接口的注解 下面演示了传递多个参数的接口

4、Swagger接口生成工作原理：

5、访问Swagger的页面路径

--------------------

## 1、首先添加Swagger的依赖 ##

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

## 2、在接在类名以及方法上面添加对应的注解 ##

首先向普及一下常用的注解

**@Api**：修饰整个类，描述Controller的作用

**@ApiOperation：**描述一个类的一个方法，或者说一个接口

**@ApiParam：**单个参数描述

**@ApiModel**：用对象来接收参数

**@ApiModelProperty**：用对象接收参数时，描述对象的一个字段

**@ApiResponse：**HTTP响应其中1个描述

**@ApiResponses：**HTTP响应整体描述

**@ApiIgnore：**使用该注解忽略这个API

**@ApiError** ：发生错误返回的信息

**@ApiImplicitParam：**一个请求参数

**@ApiImplicitParams**：多个请求参数

**其中@ApiImplicitParam的属性比较多**

<table style="width:500px;"> 
 <thead> 
  <tr> 
   <th style="width:111px;">属性</th> 
   <th style="width:185px;">取值</th> 
   <th style="width:203px;">作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="width:111px;">paramType&nbsp;</td> 
   <td style="width:185px;"></td> 
   <td style="width:203px;">查询参数类型</td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">path</td> 
   <td style="width:203px;">以地址的形式提交数据@PathVariable注解取值<br> &nbsp;</td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">query&nbsp;</td> 
   <td style="width:203px;">直接跟参数完成自动映射赋值@RequestParam取参数</td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">body&nbsp;</td> 
   <td style="width:203px;">以流的形式提交 仅支持POST @RequestBody取参数</td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">from</td> 
   <td style="width:203px;">以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">header&nbsp;</td> 
   <td style="width:203px;">参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td style="width:111px;">dataType&nbsp;</td> 
   <td style="width:185px;"></td> 
   <td style="width:203px;"></td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">Long&nbsp;</td> 
   <td style="width:203px;"></td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">String</td> 
   <td style="width:203px;">默认是String</td> 
  </tr> 
  <tr> 
   <td style="width:111px;">name</td> 
   <td style="width:185px;"></td> 
   <td style="width:203px;">接收参数名</td> 
  </tr> 
  <tr> 
   <td style="width:111px;">value&nbsp;</td> 
   <td style="width:185px;"></td> 
   <td style="width:203px;">接收参数的意义描述</td> 
  </tr> 
  <tr> 
   <td style="width:111px;">required&nbsp;</td> 
   <td style="width:185px;"></td> 
   <td style="width:203px;"></td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">true</td> 
   <td style="width:203px;">表示为必须传递的参数</td> 
  </tr> 
  <tr> 
   <td style="width:111px;"></td> 
   <td style="width:185px;">false</td> 
   <td style="width:203px;">非必填参数</td> 
  </tr> 
  <tr> 
   <td style="width:111px;">defaultValue&nbsp;</td> 
   <td style="width:185px;"></td> 
   <td style="width:203px;">默认值</td> 
  </tr> 
 </tbody> 
</table>

## 3、演示代码 ##

#### 实体类的注解 ####

@Data
    public class Student{
    
        @ApiModelProperty("学生id")
        private String Id; 
        
        @ApiModelProperty("学生姓名")
        private String name; 
    
        @ApiModelProperty("学生年龄")
        private int age; 
    }

#### 接口的注解 下面演示了传递多个参数的接口 ####

@Api(value="学生接口",description = "学生接口，提供学生信息的增、删、改、查")
    public interface StudentControllerApi {
       
      @ApiOperation("查询学生信息")
        @ApiImplicitParams({ @ApiImplicitParam(name="name",value ="学生姓名",required=true,paramType="path",dataType="String"),
                @ApiImplicitParam(name="age",value = "
    学生年龄",required=true,paramType="path",dataType="int")
        })
        public Student findStudent(String name , int age) ;
    }

Controller代码，以上只是接口的提供方，下面我们看怎样接收接口的参数

@RestController
    @RequestMapping("/student/")
    public class StudentController implements StudentControllerApi {
    
        @Autowired
        private StudentService studentService;
    
        /**
         * 根据id 查询cmsconfig表的页面信息
         * @param id
         * @return
         */
        @Override
        @GetMapping("/get/{name}/{age}")
        public Student findStudent( @PathVariable("name") String name，@PathVariable("age") int age) {
            return studentService.findStudent(name,age);
        }
    }

## 4、Swagger接口生成工作原理： ##

1、系统启动，扫描到api工程中的Swagger2Configuration类  
2、找到在此类中指定了包路径开始扫描，找到在此包下及子包下标记有@RestController注解的controller类  
3、根据controller类中的Swagger注解生成接口文档。

## 5、访问Swagger的页面路径 ##

启动项目之后

查看接口文档，浏览器访问 http://localhost:8080/swagger-ui.html 端口路径要改成自己的