十三、企业开发(4)

本章概要

  • Swagger 2

13.4 Swagger 2 简介

Swagger 2 是一个开源软件框架,可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务,它将代码和文档融为一体,使开发人员将大部分精力集中到业务中,而不是繁杂琐碎的文档中。

13.4.2 整合 Spring Boot

创建 Spring Boot Web项目 ,添加 Swagger 2 依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>

接下来创建 Swagger 2 的配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.sang.controller"))
                .build().apiInfo(new ApiInfoBuilder()
                .description("微人事接口测试文档")
                .contact(new Contact("唐三","http://www.baidu.com","tangsan@qq.com"))
                .version("v1.0")
                .title("API 测试文档")
                .license("Apache2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").build());
    }
}

代码解释:

  • 首先通过 @EnableSwagger2 注解开启 Swagger 2,然后最主要的是配置一个 Docket
  • 通过 apis 方法配置要扫描的 controller 位置,通过 paths 方法配置路径
  • 在 apiInfo 中构建文档的基本信息,例如描述,联系人信息、版本、标题等

然后开发接口

@RestController
@Api(tags = "用户数据接口")
public class UserController {

    @ApiOperation(value = "查询用户", notes = "根据id查询用户")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id) {
        return "/user/" + id;
    }

    @ApiResponses({
            @ApiResponse(code = 200,message = "删除成功"),
            @ApiResponse(code = 200,message = "删除失败")
    })
    @ApiOperation(value = "删除用户",notes = "通过id删除用户")
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id) {
        return id;
    }

    @ApiOperation(value = "添加用户",notes = "添加一个用户,传入用户名和地址")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "username",value = "用户名",required = true,defaultValue = "tangsan"),
            @ApiImplicitParam(paramType = "query",name = "address",value = "用户地址",required = true,defaultValue = "ribensheng"),
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username,@RequestParam String address){
        return username+":"+address;
    }

    @ApiOperation(value = "修改用户",notes = "修改用户,传入用户信息")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user){
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore
    public void ingoreMethod(){

    }
}

代码解释:

  • @Api 注解用在类上,用来描述整个Controller 信息
  • @ApiOperation 注解用在开发方法上,用来描述一个方法的基本信息,value 是对方法作用的一个简短描述,notes 则用来备注该方法的详细作用
  • @ApiImplicitParam 注解用在方法上,用来描述方法的参数,paramType 是指方法参数的类型,可选值有 path(参数获取方式 @PathVariable)、query(参数获取方式 @RequestParam)、header(参数获取方式 @RequestHeader)、body以及form;name 表示参数名称,和参数变量对应;value 是参数的描述信息;required 表示该字段是否必填;defaultValue 表示该字段的默认值。注意这里的 required 和 defaultValue 等字段只是文档上的约束描述,并不能真正约束接口,约束接口还需要在 @RequestParam 中添加相关属性。如果方法有多个参数,可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中
  • @ApiResponse 注解是对响应结果的描述,code 表示响应码,message 表示相应的描述信息,若有多个 @ApiResponse,则放在一个 @ApiResponses 中
  • 在 updateUser 方法中,使用 @RequestBody 注解来接收数据,此时可以通过 @ApiModel 注解和 @ApiModelProperty 注解配置User 对象的描述信息
  • @ApiIgnore 注解表示不对某个接口生成文档

相关实体类 User

@ApiModel(value = "用户实体类",description = "用户信息描述类")
public class User {

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "用户地址")
    private String address;

    @Override
    public String toString(){
        return "username:"+username+",address:"+address;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

最后启动 Spring Boot 项目,“http://localhost:8080/swagger-ui.html”,查看接口文档
在这里插入图片描述

展开用户数据接口,即可看到所有接口的描述
在这里插入图片描述

点击添加用户,查看接口详情
在这里插入图片描述

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

一只小熊猫呀

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值