SpringBoot整合Swagger2

最新推荐文章于 2024-04-11 09:46:18 发布

靖瑶_

最新推荐文章于 2024-04-11 09:46:18 发布

阅读量137

点赞数 1

分类专栏： springboot 文章标签： spring boot swagger2

本文链接：https://blog.csdn.net/weixin_52380943/article/details/117224354

版权

springboot 专栏收录该内容

18 篇文章 0 订阅

订阅专栏

1.添加maven依赖

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

2.添加Swagger2配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    //api接口文档包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.example.studydemo";

    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("图片查看添加测试服务") //设置文档的标题
                .description("图片查看添加测试服务 API 接口文档") // 设置文档的描述
                .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
                .build();
    }
}

3.创建api接口

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;


@Api(description = "图片上传接口")
@RestController
public class PicturedemoController {


    @ApiOperation(value = "没有参数的查看")
    @RequestMapping(value = "/findAll",method = RequestMethod.GET)
    @ResponseBody
    public String findAll(){
        return  "查看完成";
    }



    @ApiOperation(value = "添加图片")
    @RequestMapping(value = "/addPicture",method = RequestMethod.POST)
    @ApiImplicitParam(name = "name",value = "图片名字",required = true)
    @ResponseBody
    public String addPicture(@RequestBody String name){
        return  name;
    }



    @ApiOperation(value = "添加图片全部信息")
    @RequestMapping(value = "/addPictures",method = RequestMethod.POST)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "图片名字",dataType = "String",paramType = "query",required = true),
            @ApiImplicitParam(name = "size",value = "图片大小",dataType ="String",paramType = "query",required = true)
    })
    @ResponseBody
    public String addPictures(@RequestBody String name, String size){
        return  "图片名称"+name+"大小"+size;
    }


}

这里提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket 类，这个类中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，描述等信息，使用的协议等等。

这样！Swagger2就算配置成功了，非常方便。

启动项目，输入http://localhost:8889/swagger-ui.html#，能够看到下面页面，说明已经配置成功了：端口号根据自己的项目来，我的项目配置的是8889

在这里插入图片描述

**注：swagger2注解功能**
 @Api注解可以用来标记当前Controller的功能。
 @ApiOperation注解用来标记一个方法的作用。
 @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

@Data
@Schema(description = "新增会员")
public class AccountAddReq {

    @ApiModelProperty(name = "type", value = "注册类型", required = true)
    private Integer type;

    @ApiModelProperty(name = "mobile", value = "注册手机号", required = true)
    @Pattern(regexp = PatternConstant.MOBILE_PATTERN)
    @NotEmpty(message = "注册手机号不能为null")
    private String mobile;

    @ApiModelProperty(name = "password", value = "密码", required = true)
    @NotEmpty(message = "密码不能为空")
    private String password;

    @ApiModelProperty(name = "code", value = "验证码", required = true)
    @NotEmpty(message = "验证码不能为空")
    private String code;
}

Swagger2注解详解

1、@Api ：请求类的说明

@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags=“说明该类的作用”
value=“该参数没什么意义，所以不需要配置”

举例：

@Api(tags = "账户模块")
@RestController
@RequestMapping("/api/account")
public class AccountController {
    //TODO
}

2、@ApiOperation：方法的说明

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

举例：

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@PostMapping("/ updatepassword")
public AjaxResult updatePassword(@AutosetParam SessionInfo sessionInfo,
        @RequestBody @Valid PasswordModel passwordModel) {
}

3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（请求体）–> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType=“int”
defaultValue：参数的默认值

举例：

@ApiOperation(value="登录",notes="描述----")
@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password ){
    //TODO
    return AjaxResult.OK();
}

单个参数举例

@ApiOperation("根据用户Id删除")
@ApiImplicitParam(name="userId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
    //TODO
}

4、@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

举例：

@ApiOperation(value = "设置密码", notes = "方法的备注说明，如果有可以写在这里")
@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径找不到")
})
@PostMapping("/updatepassword")
public AjaxResult updatepassword(@AutosetParam SessionInfo sessionInfo,
        @RequestBody @Valid PasswordModel passwordModel) {
    //TODO
}

6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义

@ApiModel和 @ApiModelProperty举例：

@ApiModel("修改密码所需参数封装类")
public class PasswordModel
{
    @ApiModelProperty("用户Id")
    private String accountId;
//TODO
}

---------加油每一天------

靖瑶_

关注

1
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
SpringBoot整合Swagger2

1.添加maven依赖<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version></dependency><dependency> <groupId>io.springfox</g
复制链接

扫一扫