专栏首页SpringBoot 核心技术使用Swagger2作为文档来描述你的接口信息

使用Swagger2作为文档来描述你的接口信息

知识改变命运,撸码使我快乐,你的发迹线还好吗? 点赞再看,养成习惯 本篇文章对应源码码云(Gitee)仓库 https://gitee.com/minbox-projects/api-boot-chapter,您的Star是给我最大动力

接口文档在前后分离的项目中是必不可少的一部分,文档的编写一直以来都是一件头疼的事情,写程序不写注释不写文档这几乎是程序员的通病,Swagger2的产生给广大的程序员们带来了曙光,只需要在接口类或者接口的方法上添加注解配置,就可以实现文档效果,除了可以应用到单体应用,在微服务架构中也是可以使用的,只需要整合zuul就可以实现各个服务的文档整合。

本文所需ApiBoot相关链接:

前言

ApiBoot Swagger内部封装了Swagger2,只需要一个注解@EnableApiBootSwagger就可以实现集成,使用起来非常简单。

ApiBoot Swagger提供了一系列的默认配置,比如:文档标题文档描述文档版本号等,如果需要修改文档的默认配置,只需要在application.yml文件内对应配置参数即可实现自定义,告别了繁琐的代码配置,ApiBoot通过自动化配置的方式来实现这一点,可以查看 ApiBootSwaggerAutoConfiguration 配置类源码了解详情。

ApiBoot Swagger支持在线调试集成OAuth2的接口,只需要在文档界面通过 "Authorize"按钮设置有效的AccessToken即可。

可配置参数一览

ApiBoot Swagger之所以可以只需要一个注解就可以实现Swagger2的集成,其中难免有很多的配置参数在做支持,了解每一个配置参数的作用,我们才能进行心应手的自定义调整。

参数名

默认值

描述

api.boot.swagger.enable

true

是否启用文档

api.boot.swagger.title

ApiBoot快速集成Swagger文档

文档标题

api.boot.swagger.description

-

文档描述

api.boot.swagger.base-package

SpringBoot默认package,详见AutoConfigurationPackages

生成文档的基础package

api.boot.swagger.version

ApiBoot的版本号

文档版本号

api.boot.swagger.authorization.name

授权名称

api.boot.swagger.authorization.key-name

Authorization

整合Oauth2后AccessToken在Header内的Name


上面是常用的参数,更多配置参数详见官方文档:http://apiboot.minbox.io/zh-cn/docs/api-boot-swagger.html

创建示例项目

我们先来创建一个SpringBoot应用程序,在项目的pom.xml文件内添加ApiBoot的相关依赖,如下所示:

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.minbox.framework</groupId>
    <artifactId>api-boot-starter-swagger</artifactId>
  </dependency>

</dependencies>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.minbox.framework</groupId>
      <artifactId>api-boot-dependencies</artifactId>
      <version>2.2.1.RELEASE</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

启用ApiBoot Swagger

通过@EnableApiBootSwagger注解来启用ApiBoot Swagger,该注解可以配置在XxxApplication入口类上,也可以配置在被@Configuration注解修饰的配置类上。

@SpringBootApplication
@EnableApiBootSwagger
public class ApibootSwaggerDescribeTheInterfaceApplication {

    public static void main(String[] args) {
        SpringApplication.run(ApibootSwaggerDescribeTheInterfaceApplication.class, args);
    }

}

修改默认配置

ApiBoot Swagger所提供的配置参数都可以在application.yml文件内进行设置或修改默认值,下面是修改了版本号标题的配置:

# ApiBoot相关配置
api:
  boot:
    swagger:
      # 配置文档标题
      title: 接口文档
      # 配置文档版本
      version: v1.0

测试控制器

为了方便演示Swagger文档的强大之处,我们来创建一个测试的控制器,使用Swagger提供的注解来描述测试接口,如下所示:

/**
 * 示例控制器
 *
 * @author 恒宇少年
 */
@RestController
@RequestMapping(value = "/user")
@Api(tags = "用户控制器")
public class UserController {
    /**
     * 示例:
     * 根据用户名查询用户基本信息
     *
     * @param name {@link UserResponse#getName()}
     * @return {@link UserResponse}
     */
    @GetMapping(value = "/{name}")
    @ApiOperation(value = "查询用户信息", response = UserResponse.class)
    @ApiResponse(code = 200, message = "success", response = UserResponse.class)
    public UserResponse getUser(@PathVariable("name") String name) {
        return new UserResponse(name, 25);
    }
    /**
     * 响应实体示例
     */
    @ApiModel
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public static class UserResponse {
        @ApiModelProperty(value = "用户名")
        private String name;
        @ApiModelProperty(value = "年龄")
        private Integer age;
    }
}

注意:ApiBoot Swagger只是针对Swagger进行了封装,实现了快速集成,对内部的注解以及配置不做修改。

运行测试

启动本章项目源码,访问:http://localhost:8080/swagger-ui.html 查看运行效果,如下图所示:

image

当我们点击 "用户控制器" 时可以展开该Controller内定义的接口列表,每一个接口都提供了 "Try it out"(在线调试)功能。

本章并没有集成OAuth2,在执行在线调试时并不需要配置AccessToken

敲黑板,划重点

ApiBoot Swagger的实现主要归功于SpringBoot自定义Starter,根据配置参数进行条件配置控制对象的实例化,通过@Import来导入Swagger所需要的配置类。

代码示例

如果您喜欢本篇文章请为源码仓库点个Star,谢谢!!! 本篇文章示例源码可以通过以下途径获取,目录为apiboot-swagger-describe-the-interface

作者个人 博客 使用开源框架 ApiBoot 助你成为Api接口服务架构师

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • ApiBoot - ApiBoot Security Oauth 依赖使用文档

    ApiBoot是一款基于SpringBoot1.x,2.x的接口服务集成基础框架, 内部提供了框架的封装集成、使用扩展、自动化完成配置,让接口开...

    恒宇少年
  • ApiBoot - ApiBoot Swagger 使用文档

    ApiBoot是一款基于SpringBoot1.x,2.x的接口服务集成基础框架, 内部提供了框架的封装集成、使用扩展、自动化完成配置,让接口开...

    恒宇少年
  • ApiBoot:《SpringBoot》整合组件接口服务框架落地解决方案

    ApiBoot是一款基于SpringBoot2.x的接口服务集成基础框架,内部提供了框架的封装集成,让接口开发者完成开箱即用,不再为搭建接口框架而犯愁,从而极大...

    恒宇少年
  • ApiBoot - ApiBoot Security Oauth 依赖使用文档

    ApiBoot是一款基于SpringBoot1.x,2.x的接口服务集成基础框架, 内部提供了框架的封装集成、使用扩展、自动化完成配置,让接口开...

    恒宇少年
  • 《Java程序设计基础》 第4章手记

    《Java程序设计基础》 第4章手记 本章主要内容 - 语句和复合语句 - 分支结构 - 循环结构 - 跳转语句 这四部...

    Steve Wang
  • Spring注解@Autowired源码分析

    该方法就是在属性注入populateBean中调用的pvs = ibp.postProcessPropertyValues(pvs, filteredPds, ...

    大王叫下
  • intellij IDEA配置tomcat

    如果网上流传的方法(即方法2)不能配置成功,点击加号什么都没有的话,请看方法一配置方法。

    王小雷
  • 通俗易懂,JDK 并发容器总结

    目录: 一 JDK 提供的并发容器总结二 ConcurrentHashMap三 CopyOnWriteArrayList3.1 CopyOnWriteArra...

    Java技术江湖
  • DOC文档注释,让你的代码如此清晰。

    三哥
  • Categorical DQN-一种建模价值分布的深度强化学习方法!

    之前介绍的DQN及其各种变体,网络输出的都是状态-动作价值Q的期望预估值。而本文将介绍的Categorical DQN,它建模的是状态-动作价值Q的分布。这样的...

    石晓文

扫码关注云+社区

领取腾讯云代金券