摘要: 原文可阅读 http://www.iocoder.cn/Fight/web-api-doc 「老梁」欢迎转载,保留摘要,谢谢!
接下来的这几期,bug菌想跟大家分享一下自己昨天刚接到一个临时的需求,热乎着呢,想分享一下自己是如何面对临时需求并制定整个开发周期,其中包括从梳理业务到创建业务表再到实现业务逻辑形成闭环再到与前端对接,其中会穿插一些业务拓展及功能性拓展,这一条龙流程在线与大家一起见证,分享给刚入门的小伙伴,希望对你们有所帮助。
首先声明下,apidoc是基于注释来生成文档的,它不基于任何框架,而且支持大多数编程语言,为了springboot系列的完整性,所以标了个题。 一、apidoc简介 apidoc通过在你代码的注释来生
然后紧接着 service 模块也引入了 common_utils 了为啥呢,看下图
在微服务构建的过程中,你也许发现写的那些restful风格的接口需要编写文档。 文档一般包括要输入哪些参数,哪些参数是必填的,哪些是选填的。还有返回结果的格式以及结果示例。 也许你可以通过在git上写markdown文档来做这些事情。 但每个接口对应的文档地址这些对应关系你又需要关心。 通过swagger,这一切你都不需要做了。 在你编写自己的restful接口的时候,只需要添加一些annotation就可为你自动的生成接口文档。你上面的那些内容都为你自动生成。 甚至连简单的功能测试表单都为你做好了。 总
http://localhost:8080/swagger-ui/index.html
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
本文档中的所有示例都使用Javadoc-Style(可用于C#,Go,Dart,Java,JavaScript,PHP,TypeScript和所有其他支持Javadoc的语言):
1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4) 2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行集成完成) 没有集成的请参见 SpringBoot集成springfox-swagger2构建restful API SpringMVC集成springfox-swagger2构建restful API 官网WIKI 常用注解: – @Api()用于类; 表示标识这个类是swagger的资源 – @ApiOperation()用于方法; 表示一个http请求的操作 – @ApiParam()用于方法,参数,字段说明; 表示对参数的添加元数据(说明或是否必填等) – @ApiModel()用于类 表示对类进行说明,用于参数用实体类接收 – @ApiModelProperty()用于方法,字段 表示对model属性的说明或者数据操作更改 – @ApiIgnore()用于类,方法,方法参数 表示这个方法或者类被忽略 – @ApiImplicitParam() 用于方法 表示单独的请求参数 – @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率。 听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下。 一:Swagger介绍Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,同时swagger-ui还可以测试spring restful风格的接口功能。 官方网站为:http://swagger.io/ 中文网站:http://www.sosoapi.com
前言:作为一个以前后端分离为模式开发小组,我们每隔一段时间都进行这样一个场景:前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。
项目设计阶段写的接口文档,需求的不断的改动,导致前期定义的接口已面目全非。如果没有及时更新接口文档,那么这些接口文档对前端开发人员将是一场灾难!由于项目紧急,是没有时间完善接口文档,我们该如何提高前后端的开发效率呢?
作为一个以前后端分离为模式开发小组,我们每隔一段时间都进行这样一个场景:前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。对于这样的问题,之前一直没有很好的解决方案,直到它的出现,没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库,一款真正的开发神器。
“ Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步 ”
随着视频智能安防监控系统的不断普及,安防监控平台在各行各业的项目中也得到了充分利用。未来AI智能将会成为安防监控的主导方向,TSINGSEE青犀视频根据行业需求,不断提升现有产品的适应能力,将进一步推动智能安防监控系统的发展。
记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情。也许多点,也许少点。甚至,接口总是需要适应新需求的,修改了,增加了,这份文档维护起来就很困难了。于是发现了swagger,自动生成文档的工具。
初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情。也许多点,也许少点。甚至,接口总是需要适应新需求的,修改了,增加了,这份文档维护起来就很困难了。于是发现了swagger,自动生成文档的工具。 swagger介绍 首先,官网这样写的: Swagger – The World's Most Popular Framework for APIs. 因为自强所以自信。swagger官方更新很给力,各种版本的更新都有。swagger
上面的方案全局生效,当全局的格式化方式无法满足我们需求时,我们对日期格式要做特殊的处理:在类的属性上添加注解
等额本息法最重要的一个特点是每月的还款额相同,从本质上来说是本金所占比例逐月递增,利息所占比例逐月递减,月还款数不变。
@Profile({"dev", "test"}) 只在开发和测试环境启用 swagger。
接口文档想必是许多开发小伙伴的噩梦,不仅要写详细,还要及时维护文档与后端代码保持一致,稍有没及时更新接口文档,前端同学肯定会抱怨后端同学给的文档与实际情况不一致。
上一篇《简单搭建SpringBoot项目》讲了简单的搭建SpringBoot 项目,而 SpringBoot 和 Swagger-ui 搭配在持续交付的前后端开发中意义重大,Swagger 规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,对调用方而言非常直观,接口也可以点击try it out!按钮 进行调试,在实际开发中大大增加了开发效率。点击可了解更多 swagger 相关信息swagger-ui官网
在开发中我们经常会碰到这种情况:后台开发人员在开发完接口之后给前台人员调用,前台人员对接口的作用以及接口中的参数往往不懂,这样前台不得不多次跟后台人员沟通交流,很浪费时间。但使用Swagger后,这种情况就几乎不存在了,因为后台开发人员在写接口的同时便把接口及参数的注释写好了,在Swagger页面可以非常清楚明了的看到各个接口以及各个参数的意思。
上面就是简单的实现redis的存数据,取数据。具体怎么用看你们,如果redis不会安装可以去看看简单的安装教程。这里就不一一描述了。
Swagger的原生UI展示的内容主观上没有那么清楚和漂亮,对此有两款对应的Swagger UI的出现,分别为SwaggerBootstrapUI和 knife4j
1. 下载Node.js官方Windows版程序: https://nodejs.org/download/ 从0.6.1开始,Node.js在Windows平台上提供了两种安装方式,一是.MSI安装文件,另外还有一个.EXE可执行文件。 我选择了.EXE文件。因为.MSI安装文件除了将node.exe复制到C:\Program File (x86)\目录中及修改系统Path之外,没发现还有其他作用。 我使用的版本为v0.12.5: https://nodejs.org/dist/v0.12.5/node.exe
需求:controller方法获取数据列表,orderPackagePayedAmount等于desc时按照packagePayedAmount字段倒叙排序,等于asc时按照packagePayedAmount字段正叙排序. @Api("项目管理") @RestController @RequestMapping("/project") @Validated public class ProjectController extends BaseController { @ApiOperation(valu
说明 第一步:创建项目 浏览器打开:https://start.spring.io/,生成一个spring boot项目 📷 点击Generate这个按钮,下载项目包文件 第二步:导入开发工具 打开下载目录,解压项目文件 📷 启动idea,引入项目文件 📷 第三步:引入swagger-ui包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <versi
接口文档对于前后端开发人员都十分重要。 尤其近几年流行前后端分离后接口文档又变成重中之重。 接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新, 导致前端人员抱怨接口文档和实际情况不一致。 很多人员会抱怨别人写的接口文档不规范,不及时更新。 当时自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。 如果接口文档可以实时动态生成就不会出现上面问题。 Swagger 可以完美的解决上面的问题。
Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因:
Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.
之前我们在写项目的实体类的时候,只是简单的写一个实体类,但是现在我们想要让实体类在swagger界面显示,
@Api 注解用于标注一个Controller(Class)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。
bootstrap-ui 访问 http://localhost:8081/doc.html
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
Swagger接口管理文档 访问接口文档的网页:http://localhost:8080/swagger-ui/index.html 导入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 编写yaml SpringBoot 2.6以上版本修改了路径匹配规则
Swagger是一套围绕Open API规范构建的开源工具,可以帮助设计,构建,记录和使用REST API。
简单的来说,Swagger2的诞生就是为了解决前后端开发人员进行交流的时候API文档难以维护的痛点,它可以和我们的Java程序完美的结合在一起,并且可以与我们的另一开发利器Spring Boot来配合使用。
启动 访问:http://localhost:8080/api/swagger-ui.html
项目中我们会将响应封装成json返回,一般我们会将所有接口的数据格式统一, 使前端对数据的操作更一致、轻松。
在团队开发中,一个好的 API 文档不但可以减少大量的沟通成本,还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,并在程序员之间代代相传。这种做法存在以下几个问题:
在swagger2版本中,需要使用swagger2,并可以从浏览器中ui渲染,必须导入两个依赖 (这里放的是使用人数最多的依赖版本)
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。
领取专属 10元无门槛券
手把手带您无忧上云