失眠网 > Spring Boot API 接口文档 Swagger 入门

Spring Boot API 接口文档 Swagger 入门

时间：2022-08-09 21:46:54

转载自芋道 Spring Boot API 接口文档 Swagger 入门

摘要: 原创出处 /Spring-Boot/Swagger/ 「芋道源码」欢迎转载，保留摘要，谢谢！

本文在提供完整代码示例，可见 /YunaiV/SpringBoot-Labs 的 lab-24 目录。
原创不易，给点个 Star 嘿，一起冲鸭！

1. 概述

目前，大多数系统都采用前后端分离。在享受前后端分离的好处的同时，接口联调往往成为团队效率的瓶颈，甚至产生前后端的矛盾。简单归结来说，有几方面的原因：

问题一，接口设计滞后。后端团队往往不喜欢 API 接口设计先行，提前和前端沟通好接口。而在开发阶段的中后期，在后端提供 API 接口后，而这些接口和前端的预期有一些偏差，很容易就产生抱怨，特别是项目周期比较紧张的情况下。

问题二，接口不规范。当团队里没有同意明确的接口规范时，又或者代码 Review 做的不是很好的情况下，千奇百怪、各式各样的 API 接口可能就产生了。前端在对接这样的 API 接口，苦不堪言，在一口 mmp 一嘴 fuck xxx 之中，调完接口。

问题三，接口文档更新不及时，或者遗忘更新。因为后端 API 代码和 API 接口在两个地方，我们无法保证提交 API 代码的同时，及时更新文档。有的时候，我们甚至会遗忘更新 API 接口。随着时间的流逝，API 文档和 API 接口不一致的地方越来越多，前端会对 API 接口的信任度越来越低，然后不知道不觉之中，回到原始时代，直接问后端开发 API 是什么样的。

对于问题一和问题二，更多是开发流程上的问题，所以不在本文的范围内。当然话痨的艿艿，还是要给点粗浅的建议，完全拦不住我啊。

接口设计先行。设计完成后，后端和前端进行简单沟通，看看是否能够满足诉求。

统一的接口规范。一定要制定统一的接口规范文档，即使比较简陋，也能保证团队的 API 接口相对统一一致。😈 即使错，咱也错的一模一样，而不是千奇百怪。当然，接口规范是无法覆盖到所有的场景的，借助于“接口设计先行”，我们可以提前去 Review 每个接口的设计。

对于问题三，就进入了本文的主角 Swagger。通过在 API 接口上，添加相应的 Swagger 提供的注解，自动生成 API 文档。酱紫，API 接口和文档就在一起了，从此过上了幸福快乐的生活。

FROM 《RESTful 风格的 Web 服务框架 Swagger》
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

预览图

2. 快速入门 Swagger

示例代码对应仓库：lab-24-apidoc-swagger 。

在本小节，我们来快速入门 Swagger ，可以更加直观的感受到其提供的便利性。

2.1 引入依赖

在pom.xml文件中，引入相关依赖。

<?xmlversion="1.0"encoding="UTF-8"?><projectxmlns="/POM/4.0.0"xmlns:xsi="/2001/XMLSchema-instance"xsi:schemaLocation="/POM/4.0.0/xsd/maven-4.0.0.xsd"><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.3.RELEASE</version><relativePath/></parent><modelVersion>4.0.0</modelVersion><artifactId>lab-24-apidoc-swagger</artifactId><dependencies><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></dependencies></project>

具体每个依赖的作用，胖友自己认真看下艿艿添加的所有注释噢。

2.2 SwaggerConfiguration

因为 Spring Boot 暂未提供 Swagger 内置的支持，所以我们需要自己定义配置类。

在cn.iocoder.springboot.lab24.apidoc.config包路径下，创建 SwaggerConfiguration 配置类，用于配置 Swagger 。代码如下：

//SwaggerConfiguration.java@Configuration@EnableSwagger2//标记项目启用SwaggerAPI接口文档publicclassSwaggerConfiguration{@BeanpublicDocketcreateRestApi(){//创建Docket对象returnnewDocket(DocumentationType.SWAGGER_2)//文档类型，使用Swagger2.apiInfo(this.apiInfo())//设置API信息//扫描Controller包路径，获得API接口.select().apis(RequestHandlerSelectors.basePackage("cn.iocoder.springboot.lab24.apidoc.controller")).paths(PathSelectors.any())//构建出Docket对象.build();}/***创建API信息*/privateApiInfoapiInfo(){returnnewApiInfoBuilder().title("测试接口文档示例").description("我是一段描述").version("1.0.0")//版本号.contact(newContact("芋艿","","zhijiantianya@"))//联系人.build();}}

在类上，添加@EnableSwagger2注解，标记项目启用 Swagger API 接口文档。

通过#createRestApi()方法，创建 Swagger Docket Bean 。每个属性的作用，胖友看看艿艿的注释。大多数情况下，胖友使用这些属性是足够的。不过如果想看看其它配置，胖友可以自己去如下两个类翻翻：

Docket.java

ApiInfo.java

2.3 Application

创建Application.java类，配置@SpringBootApplication注解即可。代码如下：

//Application.java@SpringBootApplicationpublicclassApplication{publicstaticvoidmain(String[]args){SpringApplication.run(Application.class,args);}}

先暂时不启动项目。等我们添加好 Controller 。

2.4 UserController

在cn.iocoder.springboot.lab24.apidoc.controller包路径下，创建 UserController 类，提供用户 API 接口。代码如下：

//UserController.java@RestController@RequestMapping("/users")@Api(tags="用户API接口")publicclassUserController{@GetMapping("/list")@ApiOperation(value="查询用户列表",notes="目前仅仅是作为测试，所以返回用户全列表")publicList<UserVO>list(){//查询列表List<UserVO>result=newArrayList<>();result.add(newUserVO().setId(1).setUsername("yudaoyuanma"));result.add(newUserVO().setId(2).setUsername("woshiyutou"));result.add(newUserVO().setId(3).setUsername("chifanshuijiao"));//返回列表returnresult;}@GetMapping("/get")@ApiOperation("获得指定用户编号的用户")@ApiImplicitParam(name="id",value="用户编号",paramType="query",dataTypeClass=Integer.class,required=true,example="1024")publicUserVOget(@RequestParam("id")Integerid){//查询并返回用户returnnewUserVO().setId(id).setUsername(UUID.randomUUID().toString());}@PostMapping("add")@ApiOperation("添加用户")publicIntegeradd(UserAddDTOaddDTO){//插入用户记录，返回编号IntegerreturnId=UUID.randomUUID().hashCode();//返回用户编号returnreturnId;}@PostMapping("/update")@ApiOperation("更新指定用户编号的用户")publicBooleanupdate(UserUpdateDTOupdateDTO){//更新用户记录Booleansuccess=true;//返回更新是否成功returnsuccess;}@PostMapping("/delete")@ApiOperation(value="删除指定用户编号的用户")@ApiImplicitParam(name="id",value="用户编号",paramType="query",dataTypeClass=Integer.class,required=true,example="1024")publicBooleandelete(@RequestParam("id")Integerid){//删除用户记录Booleansuccess=false;//返回是否更新成功returnsuccess;}}

相比我们之前使用 SpringMVC 来说，我们在类和接口上，额外增加了 Swagger 提供的注解。

从使用习惯上，我比较喜欢先添加 SpringMVC 的注解，再添加 Swagger 的注解。

因为已经使用了 Swagger 的注解，所以类和方法上的注释，一般可以删除了，除非有特殊诉求。

其中涉及到的 POJO 类，有 UserAddDTO、UserUpdateDTO、UserVO 。

执行 Application 启动项目。然后浏览器访问http://127.0.0.1:8080/swagger-ui.html地址，就可以看到 Swagger 生成的 API 接口文档。如下图所示：

至此，我们已经完成了 Swagger 的快速入门。不过考虑到胖友能够更好的使用，我们来一个一个注解了解。

2.5 注解

在swagger-annotations库中，在io.swagger.annotations包路径下，提供了我们会使用到的所有 Swagger 注解。Swagger 提供的注解还是比较多的，大多数场景下，只需要使用到我们在「2.4 UserController」中用到的注解。

2.5.1 @Api

@Api注解，添加在 Controller 类上，标记它作为 Swagger 文档资源。

示例如下：

//UserController.java@RestController@RequestMapping("/users")@Api(tags="用户API接口")publicclassUserController{//...省略}

效果如下：

@Api注解的常用属性，如下：

tags属性：用于控制 API 所属的标签列表。[]数组，可以填写多个。

可以在一个Controller 上的@Api的tags属性，设置多个标签，那么这个 Controller 下的 API 接口，就会出现在这两个标签中。

如果在多个Controller 上的@Api的tags属性，设置一个标签，那么这些 Controller 下的 API 接口，仅会出现在这一个标签中。

本质上，tags就是为了分组 API 接口，和 Controller 本质上是一个目的。所以绝大数场景下，我们只会给一个 Controller 一个唯一的标签。例如说，UserController 的tags设置为"用户 API 接口"。

@Api注解的不常用属性，如下：

produces属性：请求请求头的可接受类型( Accept )。如果有多个，使用,分隔。

consumes属性：请求请求头的提交内容类型( Content-Type )。如果有多个，使用,分隔。

protocols属性：协议，可选值为"http"、"https"、"ws"、"wss"。如果有多个，使用,分隔。

authorizations属性：授权相关的配置，[]数组，使用@Authorization注解。

hidden属性：是否隐藏，不再 API 接口文档中显示。

@Api注解的废弃属性，不建议使用，有value、description、basePath、position。

2.5.2 @ApiOperation

@ApiOperation注解，添加在 Controller 方法上，标记它是一个 API 操作。

示例如下：

//UserController.java@GetMapping("/list")@ApiOperation(value="查询用户列表",notes="目前仅仅是作为测试，所以返回用户全列表")publicList<UserVO>list(){//查询列表List<UserVO>result=newArrayList<>();result.add(newUserVO().setId(1).setUsername("yudaoyuanma"));result.add(newUserVO().setId(2).setUsername("woshiyutou"));result.add(newUserVO().setId(3).setUsername("chifanshuijiao"));//返回列表returnresult;}

效果如下：

@ApiOperation注解的常用属性，如下：

value属性：API 操作名。

notes属性：API 操作的描述。

@ApiOperation注解的不常用属性，如下：

tags属性：和@API注解的tags属性一致。

nickname属性：API 操作接口的唯一标识，主要用于和第三方工具做对接。

httpMethod属性：请求方法，可选值为GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH。因为 Swagger 会解析 SpringMVC 的注解，所以一般无需填写。

produces属性：和@API注解的produces属性一致。

consumes属性：和@API注解的consumes属性一致。

protocols属性：和@API注解的protocols属性一致。

authorizations属性：和@API注解的authorizations属性一致。

hidden属性：和@API注解的hidden属性一致。

response属性：响应结果类型。因为 Swagger 会解析方法的返回类型，所以一般无需填写。

responseContainer属性：响应结果的容器，可选值为List、Set、Map。

responseReference属性：指定对响应类型的引用。这个引用可以是本地，也可以是远程。并且，当设置了它时，会覆盖response属性。说人话，就是可以忽略这个属性，哈哈哈。

responseHeaders属性：响应头，[]数组，使用@ResponseHeader注解。

code属性：响应状态码，默认为 200 。

extensions属性：拓展属性，[]属性，使用@Extension注解。

ignoreJsonView属性：在解析操作和类型，忽略 JsonView 注释。主要是为了向后兼容。

@ApiOperation注解的废弃属性，不建议使用，有position。

2.5.3 @ApiImplicitParam

@ApiImplicitParam注解，添加在 Controller 方法上，声明每个请求参数的信息。

示例如下：

//UserController.java@PostMapping("/delete")@ApiOperation(value="删除指定用户编号的用户")@ApiImplicitParam(name="id",value="用户编号",paramType="query",dataTypeClass=Integer.class,required=true,example="1024")publicBooleandelete(@RequestParam("id")Integerid){//删除用户记录Booleansuccess=false;//返回是否更新成功returnsuccess;}

效果如下：

@ApiImplicitParam注解的常用属性，如下：

name属性：参数名。

value属性：参数的简要说明。

required属性：是否为必传参数。默认为false。

dataType属性：数据类型，通过字符串 String 定义。

dataTypeClass属性：数据类型，通过dataTypeClass定义。在设置了dataTypeClass属性的情况下，会覆盖dataType属性。推荐采用这个方式。

paramType属性：参数所在位置的类型。有如下 5 种方式：

"path"值：对应 SpringMVC 的@PathVariable注解。

【默认值】"query"值：对应 SpringMVC 的@PathVariable注解。

"body"值：对应 SpringMVC 的@RequestBody注解。

"header"值：对应 SpringMVC 的@RequestHeader注解。

"form"值：Form 表单提交，对应 SpringMVC 的@PathVariable注解。

😈绝大多数情况下，使用"query"值这个类型即可。

example属性：参数值的简单示例。

examples属性：参数值的复杂示例，使用@Example注解。

@ApiImplicitParam注解的不常用属性，如下：

defaultValue属性：默认值。

allowableValues属性：允许的值。如果要设置多个值，有两种方式：

数组方式，即{value1, value2, value3}。例如说，{1, 2, 3}。

范围方式，即[value1, value2]或[value1, value2)。例如说[1, 5]表示 1 到 5 的所有数字。如果有无穷的，可以使用(-infinity, value2]或[value1, infinity)。

allowEmptyValue属性：是否允许空值。

allowMultiple属性：是否允许通过多次传递该参数来接受多个值。默认为false。

type属性：搞不懂具体用途，对应英文注释为Adds the ability to override the detected type。

readOnly属性：是否只读。

format属性：自定义的格式化。

collectionFormat属性：针对 Collection 集合的，自定义的格式化。

当我们需要添加在方法上添加多个@ApiImplicitParam注解时，可以使用 @ApiImplicitParams 注解中添加多个。示例如下：

@ApiImplicitParams({//参数数组@ApiImplicitParam(name="id",value="用户编号",paramType="query",dataTypeClass=Integer.class,required=true,example="1024"),//参数一@ApiImplicitParam(name="name",value="昵称",paramType="query",dataTypeClass=String.class,required=true,example="芋道"),//参数二})

2.5.4 @ApiModel

@ApiModel注解，添加在 POJO 类，声明 POJO 类的信息。而在 Swagger 中，把这种 POJO 类称为Model类。所以，我们下文就统一这么称呼。

示例如下：

//UserVO.java@ApiModel("用户VO")publicclassUserVO{//...省略}

效果如下：

@ApiModel注解的常用属性，如下：

value属性：Model 名字。

description属性：Model 描述。

@ApiModel注解的不常用属性，如下：

parent属性：指定该 Model 的父 Class 类，用于继承父 Class 的 Swagger 信息。

subTypes属性：定义该 Model 类的子类 Class 们。

discriminator属性：搞不懂具体用途，对应英文注释为Supports model inheritance and polymorphism.

reference属性：搞不懂具体用途，对应英文注释为Specifies a reference to the corresponding type definition, overrides any other metadata specified

2.5.5 @ApiModelProperty

@ApiModelProperty注解，添加在 Model 类的成员变量上，声明每个成员变量的信息。

示例如下：

//UserVO.java@ApiModel("用户VO")publicclassUserVO{@ApiModelProperty(value="用户编号",required=true,example="1024")privateIntegerid;@ApiModelProperty(value="账号",required=true,example="yudaoyuanma")privateStringusername;//...省略set/get方法}

效果如下：

@ApiModelProperty注解的常用属性，如下：

value属性：属性的描述。

dataType属性：和@ApiImplicitParam注解的dataType属性一致。不过因为@ApiModelProperty是添加在成员变量上，可以自动获得成员变量的类型。

required属性：和@ApiImplicitParam注解的required属性一致。

example属性：@ApiImplicitParam注解的example属性一致。

@ApiModelProperty注解的不常用属性，如下：

name属性：覆盖成员变量的名字，使用该属性进行自定义。

allowableValues属性：和@ApiImplicitParam注解的allowableValues属性一致。

position属性：成员变量排序位置，默认为 0 。

hidden属性：@ApiImplicitParam注解的hidden属性一致。

accessMode属性：访问模式，有AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE三种，默认为AccessMode.AUTO。

reference属性：和@ApiModel注解的reference属性一致。

allowEmptyValue属性：和@ApiImplicitParam注解的allowEmptyValue属性一致。

extensions属性：和@ApiImplicitParam注解的extensions属性一致。

@ApiModelProperty注解的废弃属性，不建议使用，有readOnly。

2.5.6 @ApiResponse

在大多数情况下，我们并不需要使用@ApiResponse注解，因为我们会类似UserController#get(id)方法这个接口，返回一个 Model 即可。所以@ApiResponse注解，艿艿就简单讲解，嘿嘿。

@ApiResponse注解，添加在 Controller 类的方法上，声明每个响应参数的信息。

@ApiResponse注解的属性，基本已经被@ApiOperation注解所覆盖，如下：

message属性：响应的提示内容。

code属性：和@ApiOperation注解的code属性一致。

response属性：和@ApiOperation注解的response属性一致。

reference属性：和@ApiOperation注解的responseReference属性一致。

responseHeaders属性：和@ApiOperation注解的responseHeaders属性一致。

responseContainer属性：和@ApiOperation注解的responseContainer属性一致。

examples属性：和@ApiOperation注解的examples属性一致。

当我们需要添加在方法上添加多个@ApiResponse注解时，可以使用 @ApiResponses 注解中添加多个。

至此，我们已经了解完 Swagger 项目中提供的主要注解。如果想要看到更多的 Swagger 的使用示例，可以看看艿艿开源的 onemall 项目。

咳咳咳，整理 Swagger 注解的每个属性，真的是花费时间。如果有哪个解释不到位，请一定给艿艿留言，我去优化和调整下，嘻嘻。

2.6 测试接口

在 Swagger 的 UI 界面上，提供了简单的测试接口的工具。我们仅仅需要点开某个接口，点击「Try it out」按钮。如下图：

然后，点击「Execute」按钮，即可执行一次 API 接口的调用。如下图：

在三个红圈中，我们可以看到 Swagger 给我们提供了：

提供了 curl 命令，让我们可以直接在命令行执行。

提供了 Request URL 地址，方便我们在浏览器中访问。

提供了执行结果，我们可以人肉看看，是否符合我们希望的结果。

😈 当然，实际项目开发中，艿艿还是喜欢 Postman 来测试接口，嘿嘿。

3. 更好看的 Swagger UI 界面

示例代码对应仓库：lab-24-apidoc-swagger-knife4j 。

springfox-swagger-ui提供的 UI 界面，基本能够满足我们的日常使用，但是距离好用，还是有一段距离。幸福的是，社区有人开源了swagger-bootstrap-ui项目，提供更好看且好用的 UI 界面。

具体的演示示例，可以访问：http://swagger-bootstrap-/doc.html 查看。

在「2. 快速入门 Swagger」的lab-24-apidoc-swagger示例的基础上，我们复制出lab-24-apidoc-swagger-knife4j项目，进行改造。

3.1 修改依赖

在pom.xml文件中，修改相关依赖。

<?xmlversion="1.0"encoding="UTF-8"?><projectxmlns="/POM/4.0.0"xmlns:xsi="/2001/XMLSchema-instance"xsi:schemaLocation="/POM/4.0.0/xsd/maven-4.0.0.xsd"><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.3.RELEASE</version><relativePath/></parent><modelVersion>4.0.0</modelVersion><artifactId>lab-24-apidoc-swagger-knife4j</artifactId><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring</artifactId><version>1.9.6</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-ui</artifactId><version>1.9.6</version></dependency></dependencies></project>

具体每个依赖的作用，胖友自己认真看下艿艿添加的所有注释噢。

3.2 界面一览

直接使用 Application 启动项目，无需做其它任何的变更，方便的说。

浏览器访问http://localhost:8080/doc.html地址，就可以看到新的 Swagger 生成的 API 接口文档。

😈 注意下，界面上艿艿添加的红圈和红字噢。更多功能，胖友自己看官方文档哟。非常推荐生产中，使用它，嘿嘿。

4. 更强大的 YApi

虽然说 Swagger 已经挺强大了，可以很好的完成提供后端 API 接口文档的功能，但是实际场景下，我们还是会碰到很多问题：

Swagger 没有内置 Mock 功能。在实际的开发中，在后端定义好 API 接口之后，前端会根据 API 接口，进行接口的 Mock ，从而实现前后端的并行开发。

多个项目的 API 接口文档的整合。随着微服务的流行，一个产品实际是拆分成多个微服务项目，提供 API 接口。那么，一个微服务项目，一个接口文档，肯定会气死前端。气死一个前端小哥哥没事，如果是小姐姐那多可惜啊。

所以，我们需要更加强大的 API 接口管理平台。目前艿艿团队采用的解决方案是：

后端开发，还是使用 Swagger 注解，生成 API 接口文档。

使用 YApi 可视化接口管理平台，自动调用 Swagger 提供的v2/api-docs接口，采集 Swagger 注解生成的 API 接口信息，从而录入到 YApi 中。

这样，我们既可以享受到 Swagger 带给我们编写 API 接口文档的便利性与及时性，又能享受到 YApi 的强大功能。

FROM /YMFE/yapi
YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。
基于 Json5 和 Mockjs 定义接口返回数据的结构和文档，效率提升多倍
扁平化权限设计，即保证了大型企业级项目的管理，又保证了易用性
类似 postman 的接口调试
自动化测试, 支持对 Response 断言
MockServer 除支持普通的随机 mock 外，还增加了 Mock 期望功能，根据设置的请求过滤规则，返回期望数据
支持 postman, har, swagger 数据导入
免费开源，内网部署，信息再也不怕泄露了

胖友可以访问 http://yapi./ 地址，快速体验下 Yapi 的功能。

下面，我们就一起来搭建一个 YApi 平台，美滋滋。因为 YApi 基于 NodeJS 语言开发，使用 MongoDB 作为数据库存储接口信息，所以我们需要先安装 NodeJS 和 MongoDB 。

艿艿：目前手头上只有 MacOS 和 CentOS 环境，所以如下的步骤，暂支也只保证这两个环境，抱歉~
如果使用 Windows 或者 Ubuntu 的同学，请辛苦自行解决下。

4.1 安装 MongoDB

参考《芋道 MongoDB 极简入门》文章，先进行下安装 MongoDB 数据库。

安装完成，记得参考文章，创建一个yapi数据库，后续我们会使用到。

4.2 安装 NodeJS

如果胖友是 CentOS 环境，使用yum install nodejs命令，进行安装。

如果胖友是 MacOS 环境，使用brew install node命令，进行安装。如果没有 brew 的胖友，这么 666 的神器，不赶紧安装下嘛？！

4.3 安装 yapi-cli

使用我们提供的 yapi-cli 工具，部署 YApi 平台是非常容易的。执行 yapi server 启动可视化部署程序，输入相应的配置和点击开始部署，就能完成整个网站的部署。部署完成之后，可按照提示信息，执行 node/{网站路径/server/app.js} 启动服务器。在浏览器打开指定 url, 点击登录输入您刚才设置的管理员邮箱，默认密码为登录系统（默认密码可在个人中心修改）。

#安装yapi-cli工具$npminstall-gyapi-cli--registryhttps://registry.#启动YApi平台部署工具$yapiserver在浏览器打开http://0.0.0.0:9090访问。非本地服务器，请将0.0.0.0替换成指定的域名或ip

4.4 YApi 平台部署

在浏览器打开http://127.0.0.1:9090地址，设置 YApi 平台部署的信息。如下图：

点击「开始部署」按钮，会弹出“部署日志”窗口。如下图：

耐心等待，直到出现日志如下：

初始化管理员账号成功,账号名："zhijiantianya@"，密码：""部署成功，请切换到部署目录，输入："nodevendors/server/app.js"指令启动服务器,然后在浏览器打开http://127.0.0.1:3000访问

此时，我们可以在命令行执行 ctrl-c 操作，关闭YApi 平台部署工具。

4.5 YApi 平台启动

在命令行中，执行如下命令，启动 YApi 平台。

#进入yapi部署路径$cd/Users/yunai/my-yapi/#启动yapi平台$nodevendors/server/app.jslog:-------------------------------------swaggerSyncUtilsconstructor-----------------------------------------------log:服务已启动，请打开下面链接访问:http://127.0.0.1:3000/log:mongodbloadsuccess...

项目启动完成。如果真正开始使用时，建议使用 pm2 方便服务管理维护。命令如下：

npminstallpm2-g//安装pm2cd{项目目录}pm2start"vendors/server/app.js"--nameyapi//pm2管理yapi服务pm2infoyapi//查看服务信息pm2stopyapi//停止服务pm2restartyapi//重启服务

这里，我们可以先略过这个操作，继续往下看。毕竟，咱现在的重心是先入门。

4.5 创建项目

浏览器打开http://127.0.0.1:3000/地址，输入账号密码登陆。

登陆账号，就是管理员邮箱。例如说，艿艿这里使用的是 zhijiantianya@

登陆密码，默认使用。

登陆成功后，自动跳转到主界面，点击右边的「添加项目」按钮，进入「新建项目」的界面(http://127.0.0.1:3000/add-project) 。如下图：

点击下方的「创建项目」按钮，完成项目的创建。创建成功后，我们会自动动跳转到刚才创建的项目下。如下图：

4.6 设置 Swagger 自动同步

点击「设置」栏目，然后选择「Swagger自动同步」栏目，设置 Swagger 自动同步信息。如下图：

友情提示：Swagger 默认会自动暴露项目地址/v2/api-docs接口，提供 Swagger 根据注解自动生成的 API 接口信息。胖友可以手动请求下该接口，感受下。
实际上，无论是 Swagger UI 也是基于该接口，获得 API 接口信息。

点击「保存」按钮。成功后，点击「接口」栏目，就可以看到自动同步到的接口信息。如下图：

至此，我们已经完成搭建 YApi 平台，并自动采集 Swagger 提供的 API 接口信息。YApi 的功能非常强大，一定要翻一翻官方文档哟。例如说，数据 Mock、高级 Mock 、自动化测试等等功能，都是非常值得在项目中实践使用。

666. 彩蛋

那么，在有了 API 接口文档之后，如何和前端更好的沟通呢？

一般来说，每一个版本的需求，产品都会提供 Axure 文档。后端开发在设计完接口之后，可以考虑在每个界面上，标记上使用到的接口的文档地址。注意，是接口的文档地址啊！！！例如说，登陆界面需要使用到登陆接口，那么我们可以把登陆接口对应的文档地址 http://127.0.0.1:3000/project/14/interface/api/11 标记到这个界面的原型上。

当然，做标记的原则是，需要跟产品协商好可以用来标记的区域，不能影响到他们的工作。例如说：

友情提示：Axure 也是支持团队协作的噢。如果胖友家的产品还没使用，批评（怒喷）一下他们。

这样，在原型上标记好接口之后，我们就可以找前端妹子，对着原型，顺着接口走一遍流程。如果走的很顺畅，说明咱的接口棒棒的。嘿嘿~

一定要记住，工具仅仅是工具，一定要尽早达成前后端的一致。

下面，进入话痨艿艿的碎碎念环节，分享下艿艿在 API 接口文档的心路历程。

艿艿最早是在年的时候，接触到前后端分离的架构。当时前端使用 ActionScript ，后端使用 Servlet + JDBC ，通过 JSON 数据格式做交互，开发一款 QQ 农场的网页游戏。😈 嘿嘿，不要嫌弃 Servlet + JDBC 很搓，当时才学 Java 3 个月左右。那时候吧，一个前端 + 两个后端，人少，直接 QQ 上发 API 接口的定义。是不是非常远古时代的做法，嘻嘻。

在年的时候，开始第一份工作的实习。公司管理后台前端采用的是 ExtJS ，后端使用 SpringMVC 提供接口。架构还是采用前后端分离，不过前端 JS 代码还是后端开发来编写，所以也就不存在 API 接口文档一说了。这个时候，更多的是自我约束，强制自己先设计好 API 接口，然后顺着产品原型走一圈。如果没问题，就开始编写后端 API 接口的实现。完成之后，在编写前端 JS 代码~

在年的时候，开始了又一次创业的遨游。项目的前端是 iOS 和 Android 客户端，顺理成章的还是前后端分离。因为客户端分成 iOS 和 Android 客户端版本，并且还是两个不同的开发小哥（是的，竟然没一个是小姐姐），所以艿艿只好提供 API 接口的文档。这个时候的 API 接口的文档方案比较土，土豆的土，使用的是 Word 文档 + SVN 协作。可想而知，大几十页的，一点打开的欲望都没有。😈 更痛苦的是，Word 文档的内容，是不支持 SVN 比对合并的，这就导致未来的一段时间，我们发展到 10+ 后端开发的时候，疯狂的冲突。

在年的时候，差不多是这个点吧，记忆有点模糊了。我们开始使用 Confluence 作为我们的 Wiki 工具，新的 API 接口文档自然就被调整到在上面编写，而老的 API 接口慢慢迁移上来。带来的好处不言而喻，终于解决多人协作老冲突的问题。同时，Confluence 支持 Template 模板，也比较容易的控制 API 接口的格式和规范。当然，比较大的困扰，还是文头提到的问题三，经常有同学忘记更新 API 文档，导致代码和文档越来越不一致。

在年的时候，爱倒腾的艿艿，无意中发现网易提供的 NEI 接口管理平台。当时从 Confluence 替换成 NEI 的原因，有点不太记得，好像是 NEI 更加结构化，也更加专业。毕竟，Confluence 是一个 Wiki 工具，而不是专为 API 接口设计的管理平台。当然，此时问题三还是存在的。

在年的时候，刚好开始了一个新项目，抱着比较尝试的心态，使用了 Swagger 来编写接口文档，效果其好，主要也是解决了问题三。更舒服的是，相比 NEI 上编写接口文档，😈 可以复制粘贴代码，效率也提升了蛮多。

再后来，我们引入了 YApi 接口管理平台，形成了我们 Swagger + YApi + Axure 标记的整体方案。大体就是酱紫。深夜 02:16 了，结束今天的哔哔，迎接明天的哔哔。

如果觉得《Spring Boot API 接口文档 Swagger 入门》对你有帮助，请点赞、收藏，并留下你的观点哦！

本内容不代表本网观点和政治立场，如有侵犯你的权益请联系我们处理。

网友评论

网友评论仅供其表达个人看法，并不表明网站立场。