欧博app:Spring Boot 集成 Swagger 构建接口文档

时间:1周前   阅读:76   评论:2

在应用开发过程中经常需要对其他应用或者客户端提供 RESTful API 接口,尤其是在版本快速迭代的开发过程中,修改接口的同时还需要同步修改对应的接口文档,这使我们总是做着重复的事情,而且若是遗忘修改接口文档,就可能造成不必要的贫苦。

为了解决这些问题,Swagger 就孕育而生了,那让我们先简朴了解下。

Swagger 简介

Swagger 是一个规范和完整的框架,用于天生、形貌、挪用和可视化 RESTful 气概的 Web 服务

总体目标是使客户端和文件系统作为服务器,以同样的速率来更新。文件的方式、参数和模子慎密集成到服务器端的代码中,允许 API 始终保持同步。

下面我们在 Spring Boot 中集成 Swagger 来构建壮大的接口文档。

Spring Boot 集成 Swagger

Spring Boot 集成 Swagger 主要分为以下三步:

  1. 加入 Swagger 依赖
  2. 加入 Swagger 文档设置
  3. 使用 Swagger 注解编写 API 文档

加入依赖

首先建立一个项目,在项目中加入 Swagger 依赖,项目依赖如下所示:

        <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>

加入设置

接下来在 config 包下建立一个 Swagger 设置类 Swagger2Configuration,在设置类上加入注解 @EnableSwagger2,解释开启 Swagger,注入一个 Docket 类来设置一些 API 相关信息,apiInfo() 方式内界说了几个文档信息,代码如下:

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // swagger 文档扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.wupx.interfacedoc.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试接口列表")
                .description("Swagger2 接口文档")
                .version("v1.0.0")
                .contact(new Contact("wupx", "https://www.tianheyu.top", "wupx@qq.com"))
                .license("Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

枚举其中几个文档信息说明下:

  • title:接口文档的题目
  • description:接口文档的详细形貌
  • termsOfServiceUrl:一样平常用于存放公司的地址
  • version:API 文档的版本号
  • contact:维护人、维护人 URL 以及 email
  • license:许可证
  • licenseUrl:许可证 URL

编写 API 文档

domain 包下建立一个 User 实体类,使用 @ApiModel 注解解释这是一个 Swagger 返回的实体,@ApiModelProperty 注解解释几个实体的属性,代码如下(其中 getter/setter 省略不显示):

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

    @ApiModelProperty(value = "用户 id", hidden = true)
    private Long id;

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

    @ApiModelProperty(value = "用户岁数")
    private String age;

    // getter/setter
}

最后,在 controller 包下建立一个 UserController 类,提供用户 API 接口(未使用数据库),代码如下:

@RestController
@RequestMapping("/users")
@Api(tags = "用户治理接口")
public class UserController {

    Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    public List<User> getUserList() {
        return new ArrayList<>(users.values());
    }

    @PostMapping("/")
    @ApiOperation(value = "建立用户")
    public String addUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "获取指定 id 的用户")
    @ApiImplicitParam(name = "id", value = "用户 id", paramType = "query", dataTypeClass = Long.class, defaultValue = "999", required = true)
    public User getUserById(@PathVariable Long id) {
        return users.get(id);
    }

    @PutMapping("/{id}")
    @ApiOperation(value = "凭据 id 更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户 id", defaultValue = "1"),
            @ApiImplicitParam(name = "name", value = "用户姓名", defaultValue = "wupx"),
            @ApiImplicitParam(name = "age", value = "用户岁数", defaultValue = "18")
    })
    public User updateUserById(@PathVariable Long id, @RequestParam String name, @RequestParam Integer age) {
        User user = users.get(id);
        user.setName(name);
        user.setAge(age);
        return user;
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "凭据 id 删除用户")
    @ApiImplicitParam(name = "id", value = "用户 id", dataTypeClass = Long.class, required = true)
    public String deleteUserById(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }
}

启动项目,接见 http://localhost:8080/swagger-ui.html,可以看到我们界说的文档已经在 Swagger 页面上显示了,如下图所示:

到此为止,我们就完成了 Spring Boot 与 Swagger 的集成。

同时 Swagger 除了接口文档功效外,还提供了接口调试功效,以建立用户接口为例,单击建立用户接口,可以看到接口界说的参数、返回值、响应码等,单击 Try it out 按钮,然后点击 Execute 就可以提议挪用请求、建立用户,如下图所示:

注解先容

由于 Swagger 2 提供了异常多的注解供开发使用,这里枚举一些对照常用的注解。

@Api

@Api 用在接口文档资源类上,用于符号当前类为 Swagger 的文档资源,其中含有几个常用属性:

  • value:界说当前接口文档的名称。
  • description:用于界说当前接口文档的先容。
  • tag:可以使用多个名称来界说文档,但若同时存在 tag 属性和 value 属性,则 value 属性会失效。
  • hidden:若是值为 true,就会隐藏文档。

@ApiOperation

@ApiOperation 用在接口文档的方式上,主要用来注解接口,其中包罗几个常用属性:

  • value:对API的简短形貌。
  • note:API的有关细节形貌。
  • esponse:接口的返回类型(注重:这里不是返回现实响应,而是返回工具的现实效果)。
  • hidden:若是值为 true,就会在文档中隐藏。

@ApiResponse、@ApiResponses

@ApiResponses 和 @ApiResponse 二者配合使用返回 HTTP 状态码。@ApiResponses 的 value 值是 @ApiResponse 的聚集,多个 @ApiResponse 用逗号分开,其中 @ApiResponse 包罗的属性如下:

  • code:HTTP状态码。
  • message:HTTP状态信息。
  • responseHeaders:HTTP 响应头。

@ApiParam

@ApiParam 用于方式的参数,其中包罗以下几个常用属性:

  • name:参数的名称。
  • value:参数值。
  • required:若是值为 true,就是必传字段。
  • defaultValue:参数的默认值。
  • type:参数的类型。
  • hidden:若是值为 true,就隐藏这个参数。

@ApiImplicitParam、@ApiImplicitParams

二者配合使用在 API 方式上,@ApiImplicitParams 的子集是 @ApiImplicitParam 注解,其中 @ApiImplicitParam 注解包罗以下几个参数:

  • name:参数的名称。
  • value:参数值。
  • required:若是值为 true,就是必传字段。
  • defaultValue:参数的默认值。
  • dataType:数据的类型。
  • hidden:若是值为 true,就隐藏这个参数。
  • allowMultiple:是否允许重复。

@ResponseHeader

API 文档的响应头,若是需要设置响应头,就将 @ResponseHeader 设置到 @ApiResponseresponseHeaders 参数中。@ResponseHeader 提供了以下几个参数:

  • name:响应头名称。
  • description:响应头备注。

@ApiModel

设置 API 响应的实体类,用作 API 返回工具。@ApiModel 提供了以下几个参数:

  • value:实体类名称。
  • description:实体类形貌。
  • subTypes:子类的类型。

@ApiModelProperty

设置 API 响应实体的属性,其中包罗以下几个参数:

  • name:属性名称。
  • value:属性值。
  • notes:属性的注释。
  • dataType:数据的类型。
  • required:若是值为 true,就必须传入这个字段。
  • hidden:若是值为 true,就隐藏这个字段。
  • readOnly:若是值为 true,字段就是只读的。
  • allowEmptyValue:若是为 true,就允许为空值。

到此为止,我们就先容完了 Swagger 提供的主要注解。

总结

Swagger 可以轻松地整合到 Spring Boot 中构建出壮大的 RESTful API 文档,可以削减我们编写接口文档的事情量,同时接口的说明内容也整合入代码中,可以让我们在修改代码逻辑的同时利便的修改接口文档说明,另外 Swagger 也提供了页面测试功效来调试每个 RESTful API。

若是项目中还未使用,不防实验一下,会发现效率会提升不少。

本文的完整代码在 https://github.com/wupeixuan/SpringBoot-Learn 的 interface-doc 目录下。

最好的关系就是相互成就,人人的在看、转发、留言三连就是我创作的最大动力。

参考

http://swagger.io

https://github.com/wupeixuan/SpringBoot-Learn

《Spring Boot 2 实战之旅》

,

环球UG

www.81888818.com欢迎进入环球UG官网(UG环球),环球UG官方网站:www.ugbet.net开放环球UG网址访问、环球UG会员注册、环球UG代理申请、环球UG电脑客户端、环球UG手机版下载等业务。

上一篇:皇冠代理app下载:泪!毛加恩蜜月首日 收到高以翔超感人大礼

下一篇:usdt充币教程(www.6allbet.com):成都“面街”:面香缭绕烟火味浓