Swagger解决你手写API接口文档的痛
首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结。
01
痛 苦
不做、不行
之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的API接口,写一个接口文档给到我们前端工程师,前端工程师拿到接口文档之后,根据接口文档规定的URL、请求方式(POST或GET)、请求参数、返回结果(成功或失败,失败时,返回的状态分别代表什么意思),来对接我们后端提供的API接口,如果提供的接口文档有问题,那么同样的,前端对接时,也会出现问题,前端会说是后端提供的接口文档的问题,后端觉得我可能程序更新了,没有及时更新接口文档。其实,不管是前端还是后端,都希望有一个好的接口文档,能随着程序的迭代不断更新的接口文档。
而写接口文档这种没有技术含量又苦恼的事儿,对于后端来说无疑是噩梦一般,API接口少,没几个,可能半个点一个点就完事儿了,如果API接口很多,比如说整个订单系统的接口,写接口文档这种事儿可能会耗上一天,两天,甚至三天,最后写完还不一定是对的,那个痛啊。
02
邂 逅
有痛点、抛出来
之前写API文档的方式各种各样,wiki、word、excel、text等等各种方式,万物皆可盘。
比如word:
对,word要把目录给人家定义好,要不会被喷的。
再比如excel:
还有text:
千篇一律, 能不能再乱一点,前端已经提这40米的大砍刀在向你走来。
有没有自动生成API文档的插件呢?答:有,还自带各种插件
关于SwaggerSwagger是一个功能强大且易于使用的API开发人员工具套件,适用于团队和个人,可在整个API生命周期(从设计和文档到测试和部署)中进行开发。
Swagger由开放源代码,免费和市售工具共同组成,它使任何人(从技术工程师到街头智能产品经理)都可以构建每个人都喜欢的惊人API。
Swagger由SmartBear Software构建,后者是团队软件质量工具的领导者。SmartBear落后于软件领域的一些知名公司,包括Swagger,SoapUI和QAComplete。
在Swagger官网上提供了几种工具,可以通过集成的方式来实现我们想要的效果。
Swagger Inspector:类似postman的一种API调试工具,可以点击URL,查看如何使用。https://swagger.io/docs/swagger-inspector/how-to-use-swagger-inspector/。
Swagger Codegen:是一个开源代码生成器,可直接从Swagger定义的RESTful API构建服务器存根和客户端SDK。Swagger Codegen的源代码可以在GitHub中找到,点击URL,查看如何使用。https://swagger.io/docs/open-source-tools/swagger-codegen/。
Swagger Editor:是一个开源编辑器,用于设计,定义和记录Swagger规范中的RESTful API,点击URL查看如何使用,https://swagger.io/docs/open-source-tools/swagger-editor/
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目,点击URL查看如何使用,https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/
03
接 触
收入囊中
Swagger是什么我们已经介绍完了,下面我们通过代码示例来讲解如何与Springboot结合使用。
1、引入Swagger相关jar包(Springboot相关jar自行引入)
<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、创建启动类,设置启动参数,首先创建一个class,命名为SwaggerApplication,其中managerPackage为Swagger要管理的包目录,比如com.user.api.controller,从header获取参数名为Authorization的值,可以用于验证权限(如果显示不完整请左右滑动查看全部)。
/**
* Swagger2配置类
* 在与spring boot集成时,放在与Application.java同级的目录下。
* 通过@Configuration注解,让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/
@Configuration
@EnableSwagger2
public class SwaggerApplication{
@Value(value = "${swagger.manager.package}")
private String managerPackage;
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
* @return
*/
@Bean
public Docket createRestApi(){
ParameterBuilder aParameterBuilder = new ParameterBuilder();
aParameterBuilder
.parameterType("header") //参数类型支持header, cookie, body, query etc
.name("Authorization") //参数名
.defaultValue("Authorization") //默认值
.description("token")
.modelRef(new ModelRef("string"))//指定参数值的类型
.required(false).build(); //非必需,这里是全局配置,然而在登陆的时候是不用验证的
List<Parameter> aParameters = new ArrayList<Parameter>();
aParameters.add(aParameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.groupName("v1")
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo())
.globalOperationParameters(aParameters);
}
public ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("用户管理API接口文档")
.description("用户管理API接口文档")
.termsOfServiceUrl("")
.contact("sunf")
.version("1.0")
.build();
}
}
3、添加实体类引用,PS:引用只添加DTO、VO,Entity不需要,class头注解@ApiModel,申明该类被Swagger解析,@ApiModelProperty声明各字段属性的含义。
@ApiModel(description = "用户信息")
@Data
public class Users {
@ApiModelProperty(value = "用户ID")
private String id;
@ApiModelProperty(value = "用户姓名")
private String userName;
@ApiModelProperty(value = "年龄")
private String age;
@ApiModelProperty(value = "性别")
private String sex;
@ApiModelProperty(value = "地址")
private String address;
@ApiModelProperty(value = "电话")
private String phone;
}
4、声明Controller,暴漏API接口,如果一个接口没有声明明确的调用方式(POST或GET)method = RequestMethod.POST,Swagger默认会把所有的调用方式都列出来。
@RestController
@RequestMapping("/user")
@Api(value = "用户相关接口",description = "用户信息")
public class UserController {
@Autowired
private UserService userService;
/**
* 获取用户详情
* @param userId
* @return
*/
@ApiOperation(value = "获取用户详情", notes = "根据用户ID获取用户详情")
@RequestMapping(value = "/get",method = RequestMethod.POST)
public Users get(String userId){
return userService.get(userId);
}
/**
* 获取所有用户
* @return
*/
@ApiOperation(value = "获取所有用户", notes = "获取所有用户列表")
@RequestMapping(value = "/getUserAllList",method = RequestMethod.POST)
public List<Users> getUserAllList(){
return userService.getUserAllList();
}
}
PS:未指定访问方式是这样的
5、到此Swagger的配置基本完成,启动Springboot的服务,访问Swagger内置的web页面,可以看到我们暴漏的所有API和调用方式,访问地址:http://localhost:8081/swagger-ui.html
6、点击获取用户详情的接口,try it out ,可以针对此接口进行访问调试,点击Model可以查看用户实体
7、如果是页面样式不满意,我们可以自定义页面样式,现在github已经有道友分享了自定义的ui,如何使用请查看,https://github.com/caspar-chen/swagger-ui-layer,下图是新的UI,是不是你的菜。
小结:Swagger,就是把相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件,连描述文件都不需要再去维护了。所有的信息,都在代码里面了。代码即接口文档,接口文档即代码。
微信扫一扫关注我,分享给其他人,一起成长
Swagger解决你手写API接口文档的痛的更多相关文章
- Api接口文档管理工具,你知道哪些呢?
上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...
- Swagger 生成 PHP API 接口文档
Swagger 生成 PHP API 接口文档 Lumen微服务生成Swagger文档 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文 ...
- spring boot使用swagger生成api接口文档
前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...
- SpringBoot + Swagger2 自动生成API接口文档
spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...
- 构建标准OpenStack API接口文档
1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch ...
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- Spring Boot从入门到精通(十一)集成Swagger框架,实现自动生成接口文档
Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.Swagger 是一组开源项目,其中主要要项目如下: Swagger-tools:提供各种与S ...
- api(接口)文档管理工具
api(接口)文档管理工具 欢迎光临:博之阅API管理平台 ,做为一个app开发者,还没有用到api管理工具,你就OUT了 点击进入:程序员精华博客大全
- 智表ZCELL产品V1.4.0开发API接口文档 与 产品功能清单
为了方便大家使用ZCELL,应网友要求,整理编写了相关文档,现与产品一起同步发布,供大家下载使用,使用过程中如有疑问,请与我QQ联系. 智表(ZCELL)V1.4.0版本 功能清单文档下载地址: 功 ...
随机推荐
- springmvc(二)
请求信息转换 异步发送表单数据到JavaBean,并响应JSON文本返回 操作步骤:(1)加入Jackson2或fastjson框架包,springmvc默认支持Jackon2,不需要做任何操作,而f ...
- Git很麻烦?不存在的!掌握这几招就够了
废话不多说,下面直接开始了! 查看原文 确保代码库是最新的,先用这条命令把你的代码拉取到本地 git clone -- 修改完代码后,按顺序执行下面四个命令 git pull git add * /r ...
- WCF尝试创建与发布IIS(含问题描述)
技术贴技术贴就直接讲技术来,客套的话我也不多说了,各位看官包涵包涵. 跟着园内高手一步一步发布成功,欣喜若狂之际,发个贴纪念纪念一下. 废话不多说,不正确之处,还望大家积极指出,共同进步.哈哈~~~ ...
- 彻底理解CORS跨域原理
背景 现在的前端开发中都是前后端分离的开发模式,数据的获取并非同源,所以跨域的问题在我们日常开发中特别常见.其实这种资料网上也是一搜一大堆,但是都不够全面,理解起来也不够透彻.这篇文章就结合具体的示例 ...
- [Note] GNUstep on Windows
1.下载与安装 www.gnustep.org/windows/installer.html 下载 GNUstep MSYS System GNUstep Core GNUstep Devel 并安装 ...
- Scala 数组和List
Scala 数组和List: import scala.collection.mutable.ArrayBuffer import scala.collection.mutable.Buffer ob ...
- 在Mac上搭建带ssl协议和域名指向的Apache服务器
顾名思义,就是要在苹果电脑上搭建 Apache 服务器,并且支持 https 协议,能用指定域名访问(有些开发调试需要注册域名,比如调试微信JS-SDK),当然最好能在手机端进行调试.首先,Mac 系 ...
- Kubernetes+Docker+Istio 容器云实践
随着社会的进步与技术的发展,人们对资源的高效利用有了更为迫切的需求.近年来,互联网.移动互联网的高速发展与成熟,大应用的微服务化也引起了企业的热情关注,而基于Kubernetes+Docker的容器云 ...
- UVA - 12099 The Bookcase
No wonder the old bookcase caved under the massive piles of books Tom had stacked on it. He had bett ...
- 用go语言爬取珍爱网 | 第二回
昨天我们一起爬取珍爱网首页,拿到了城市列表页面,接下来在返回体城市列表中提取城市和url,即下图中的a标签里的href的值和innerText值. 提取a标签,可以通过CSS选择器来选择,如下: $( ...