SpringBoot集成Swagger2—swagger2注解使用教程

最新推荐文章于 2023-04-13 11:24:58 发布

√Angelの爱灬

最新推荐文章于 2023-04-13 11:24:58 发布

阅读量273

点赞数

分类专栏： Swagger 文章标签： spring boot

原文链接：https://blog.csdn.net/qq_36805343/article/details/103599407

版权

Swagger 专栏收录该内容

5 篇文章 0 订阅

订阅专栏

swagger2 注解说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的作用
    value="说明方法的作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 放在请求头，请求参数的获取：@RequestHeader
            · query --> 用于get请求的参数拼接，请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body --> 放在请求体。请求参数的获取：@RequestBody(代码中接收注解)
            · form --> 文件参数   
        dataType：参数类型，默认string。其他可取值：
        	"int", "date", "string", "double", "float", "boolean", "byte", "object", 
        	"long", "date-time", "__file", "biginteger", "bigdecimal", "uuid"    
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如："请求失败：失败原因。。。。"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

1.@Api：用在请求的类上，说明该类的作用

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "测试用Controller")
public class TestContorller {

}

2. @ApiOperation：用在请求的方法上，说明方法的作用

@ApiOperation(value = "测试方法", notes = "", httpMethod = "POST")

3. @ApiImplicitParams：用在请求的方法上，包含一组参数说明

@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手机",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="int")
})

4. @ApiResponses：用于请求的方法上，表示一组响应

@ApiResponses({
    @ApiResponse(code=400,message="请求参数不对"),
    @ApiResponse(code=404,message="找不到资源")
})

5. @ApiModel：用于请求参数是类的情况下

比如

@RequestMapping(value = "/test", method = RequestMethod.POST)
public String getTeacherInfo(@RequestBody TeacherDTO teacher){
}

@ApiModel(description = "导师信息")
@Data
public class TeacherDTO {
    @ApiModelProperty(value = "ID",required=true)
    private String teacherId;
    @ApiModelProperty(value = "姓名",required=true)
    private String teacherName;
    @ApiModelProperty(value = "年龄",required=true)
    private String age;
}

踩坑记录

swagger3配置请求参数为文件类型的时候必须在参数前面加 @RequestPart(“file”) 才能在文档里显示出来

	@RequestMapping(value = "/import", method = RequestMethod.POST)
    @ApiOperation(value = "导入文件", httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "file", value = "导入的excel文件", required = true, paramType = "form", dataType = "__file", dataTypeClass = MultipartFile.class)
    })
    public R importExcel(@RequestPart("file") MultipartFile file){
        xqxxService.importExcel(file);
        return R.success();
    }