swagger2学习与使用

Posted 2021-08-30 型男一枚

文章目录

• • 什么是swagger2
  • swagger2注解的简单使用
  • • @Api：请求类的说明
    • @ApiOperation
    • @ApiImplicitParams、@ApiImplicitParam
    • @ApiResponses、@ApiResponse
    • @ApiModel：用于javaBean上，表示一个javaBean的信息
    • @ApiModelProperty：用在javaBean类的属性上说明属性的含义
  • SpringBoot2.x整合Swagger2

什么是swagger2

编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。
常用注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiImplicitParam：一个请求参数 @ApiImplicitParams：多个请求参数

swagger2注解的简单使用

@Api：请求类的说明

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

@Controller
@RequestMapping("/api")
@Api(tags = "swagger测试controller")
public class SwaggerTestController {
    @GetMapping("/test")
    @ResponseBody
    public String test() {
        return "测试成功";
    }
}

@ApiOperation

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

@ApiImplicitParams、@ApiImplicitParam

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

示例：

@Api(tags="用户模块")
@Controller
public class UserController {

    @ApiOperation(value="用户登录",notes="随边说点啥")
    @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="Integer")
    })
    @PostMapping("/login")
    public JsonResult login(@RequestParam String mobile, @RequestParam String password,
    @RequestParam Integer age){
        //...
        return JsonResult.ok(map);
    }
}

@ApiResponses、@ApiResponse

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

示例：

@Api(tags="用户模块")
@Controller
public class UserController {

    @ApiOperation("获取用户信息")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
    }) 
    @ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    }) 
    @ResponseBody
    @RequestMapping("/list")
    public JsonResult list(@RequestParam String userId) {
        ...
        return JsonResult.ok().put("page", pageUtil);
    }
}

@ApiModel：用于javaBean上，表示一个javaBean的信息

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
            （这种一般用在post创建的时候，使用 @RequestBody 这样的场景，
            请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）

@ApiModelProperty：用在javaBean类的属性上说明属性的含义

示例：

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{

    @ApiModelProperty(value = "是否成功")
    private boolean success=true;
    @ApiModelProperty(value = "返回对象")
    private Object data;
    @ApiModelProperty(value = "错误编号")
    private Integer errCode;
    @ApiModelProperty(value = "错误信息")
    private String message;
        
    /* getter/setter 略*/
}

SpringBoot2.x整合Swagger2

1. 导入Swagger2的依赖

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

2. 编写swagger2的配置文件

/**
 * Swagger2配置信息
 * 基本信息格式都是固定的，拿来修改即可
 */
@Configuration // 告诉springBoot这是一个配置类
@EnableSwagger2 // 开启swagger2
public class Swagger2Config {
    /**
     * 我们有几个总的模块我们可以创建几个Docket分组对象注册到springboot中
     * 比如我们有个前台，后台，我们注册两个Docket对象
     *
     * @return
     */
    @Bean
    public Docket webApiConfig() {

        return new Docket(DocumentationType.SWAGGER_2)
                // 给我们分组模块七个名字
                .groupName("webApi")
                // 模块的描述信息，需要我们手动创建
                .apiInfo(webApiInfo())
                //
                .select()
                //只显示api路径下的页面（我们可以指定访问路径）
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();

    }

    @Bean
    public Docket adminApiConfig() {

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();

    }

    /**
     * 模块分组的描述信息
     *
     * @return
     */
    private ApiInfo webApiInfo() {

        return new ApiInfoBuilder()
                // 标题
                .title("网站-API文档")
                // 详细描述
                .description("本文档描述了网站微服务接口定义")
                // 版本号
                .version("1.0")
                // 联系方式
                .contact(new Contact("zdk", "http://zdk.com", "[e-mail]"))
                .build();
    }

    private ApiInfo adminApiInfo() {

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("zdk", "http://zdk.com", "[e-mail]"))
                .build();
    }
}

3. 编写我们的业务代码，添加我们的swagger注解即可。