前几天在项目中集成了swagger,一切准备就绪打算将其部署到服务器时发现并不顺利,访问的时候页面白屏,由于我的nest项目采用的是单文件部署,互联网上没有找到相关的解决方案,于是我就成了第一个吃螃蟹的人。
Swagger是最流行的RESTful API开源工具,包含一整套代码库、编辑器、代码生成器等,可用于API的描述、定义、生成以及可视化等方面。我们可以在http://www.swagger.io 查看它的详细介绍,下载它的源码并集成到项目中来。Harbor是VMware新近开源的企业级容器Registry项目(http://github.com/vmware/harbor),用户可在私有环境中部署Harbor,实现容器镜像的权限管理、图形化管理、LDAP/AD认证集成以及日志审计等功能。Harbor还提供RESTful API,其他容器管理平台可以很方便地集成Harbor的功能。本文介绍如何使用Harbor内嵌的Swagger工具,调用和测试RESTful API。
现在访问 http://localhost:5000/docs 查看交互式 API 文档(Swagger UI):
借鉴大佬的帖子: https://blog.csdn.net/xiaojin21cen/article/details/78654652?ops_request_misc=%257B%2522request%255Fid%2522%253A%2522162860182416780366580688%2522%252C%2522scm%2522%253A%252220140713.130102334…%2522%257D&request_id=162860182416780366580688&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2allsobaiduend~default-2-78654652.first_rank_v2_pc_rank_v29&utm_term=swagger%E6%B3%A8%E8%A7%A3&spm=1018.2226.3001.4187
前端和后端的联调离不开API文档,而手动编写API文档是一项耗时又费力的操作。Swagger正是基于简化API文档的输出的一个优秀的开源框架,通过OpenAPI的规范呈现接口信息,方便的提供测试和联调。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
之前公司使用了swagger作为文档管理工具,原生的swagger-ui非常丑,后来改用了开源项目 萧明 / knife4j 的swagger组件进行了swagger渲染,改造之后界面漂亮多了,操作也方便了很多。
现在都奉行前后端分离开发和微服务大行其道,前后端技术在各自道路上越走越远。 前后端唯一联系变成了API接口,API文档变成了前后端开发人员&测试人员联系的纽带。所以一款强大的Restful API文档就变得至关重要了。而目前在后端领域,基本上是Swagger的天下了。
一、简介 Swagger的目标是为REST API定义一个与语言无关的标准接口,允许用户发现和理解计算机服务的功能,而无需访问源代码。当通过Swagger正确定义时,用户可以用最少量的实现逻辑理解远程服务并与之交互。类似于低级编程所做的接口。 二、实现步骤 1、添加 Maven 依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.
swagger,俗称丝袜哥,是用来生成接口文档的。没有使用swagger的时候,你写完后端接口,得自己将后端接口地址一个个地整理出来,告诉别人这个接口是干嘛的,要传哪些参数,正常情况下返回的参数是咋样的,非正常情况返回的又是咋样的。很麻烦有木有?有了丝袜哥,你只需要简单地加上几个注解,然后会有一个丝袜哥的ui界面,里面就包含了接口的所有信息,灰常地方便。
springfox 已经停止更新很久了,SpringBoot新版本都不支持。为了能够继续使用Swagger,只能调整继承库。
云商城采用了当前主流的微服务技术架构,微服务技术栈采用了当前主流的SpringCloud Alibaba技术栈,从接入层、网关层、服务层、数据同步、服务治理、数据处理、第三方接口多个方面进行了精心设计,技术经过了多次挑选、优中选优,最终打造了一套全网最优质的的微服务商城架构体系,解决了大型微服务电商应用中绝大多数难点、痛点问题。
在gRPC-Gateway集成swagger服务的过程并不简单,咱们将其中的重点提前看一下,做到心里有数:
SpringBoot 插件入门 简介 公司用的是SpringBoot,api框架用的是swagger-ui,确实用的不错,但是在使用过程中发现一个问题,就是当前端正式调用的时候,如果参数一多的话模拟请求比较麻烦,或者swagger-ui无法模拟出前端的完整请求参数,比如参数放到header里面的,就萌生了一个想法,可以不可以自己写一个类似swagger-ui的插件,通过捕捉访问进来的请求,将其header和param保存下来,下次如果出现问题的话可以通过相同的header和param来再次进行请求. 思考过
从swagger官网下载依赖文件,将disk下的文件拷贝到 packages/hanyun/swagger/src/swagger-ui/dist 下面
随着项目架构的演化,前后端分离是不可阻挡的趋势。这种模式的协作在实践的过程中经常会遇到的一个问题就是文档。
一般在使用 Spring Boot 开发前后端分离项目的时候,都会用到 Swagger。Swagger 是一个规范和完整的框架,用于生成、描述、调试和可视化 RESTful 风格的 Web API 服务框架。
我们在开发接口的时候,会将接口文档给前端的开发者进行对接。我们可以通过 Postman 或者 Yapi 等接口管理工具进行编写管理。实际开发中,接口的管理确实也应该通过专业的工具管理。
接口文档对于前后端开发人员都十分重要。 尤其近几年流行前后端分离后接口文档又变成重中之重。 接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新, 导致前端人员抱怨接口文档和实际情况不一致。 很多人员会抱怨别人写的接口文档不规范,不及时更新。 当时自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。 如果接口文档可以实时动态生成就不会出现上面问题。 Swagger 可以完美的解决上面的问题。
在使用DRF的时候,通常的文档有:默认文档RestFrameWork、CoreAPI、Swagger,Swagger是最流行的API文档库,在绝大多数服务端开发中都有用到,之前我们使用了CoreAPI来生成文档,一方面是它不够流行,没办法和其他工具结合,另一方面可能是我不熟悉,所有有些接口并不能按照我们的要求来使用。因此我选择使用Swagger文档,之前使用过drf-yasg,但是drf-yasg现在还不支持OpenAPI 3.0,而在drf-yasg的官方文档中为我们推荐了另一个库:drf-spectacular,而且声明了drf-yasg不太可能支持OpenAPI 3.0,因此推荐我们使用drf-spectacular这个库。
├── controller — 控制层(将请求通过 url 匹配,分配到不同的接收器/方法进行处理,然后返回结果)
在这里,以 Spring Boot 项目为例,给出两种自定义 Swagger2 请求 URL 路径的方法。
作为一名后台开发人员,在前后端分离项目的开发过程中,我们写好了后台接口之后总免不了要给前端同事提供一份详细的API接口文档,写完一个接口又要补充一个接口的文档,过程还挺繁琐的。那么有没有一款工具让我们不用再些这些繁琐的API文档呢?答案是有的。之前我们在项目中配置swagger结合相关的注解来生成API文档界面,只是界面不是那么美观,还必须在每个接口控制器方法中添加很多的注解,代码侵入性比较强。
magic-api是一个基于Java的接口快速开发框架,编写接口将通过magic-api提供的UI界面完成,自动映射为HTTP接口,无需定义Controller、Service、Dao、Mapper、XML、VO等Java对象。
前段时间基于我的 kz-admin 模板写了一个link-admin的项目(可以访问 link.kuizuo.cn 在线体验,账号 admin,密码a123456),是一个“一次性”充值链接管理系统,具体自行体验即可(项目未开源)。
Swagger 3.0 发布已经有一段时间了,它于 2020.7 月 发布,但目前市面上使用的主流版本还是 Swagger 2.X 版本和少量的 1.X 版本,然而作为一名合格的程序员怎么能不折腾新技术呢?所以本期就大家带来一篇最新版 Swagger 的内容,本文会带大家看最新版 Swagger 有哪些改变?又是如何将老版本 Swagger 升级到新版的?
Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specification(OpenAPI 规范,也简称 OAS)。 Swagger 可以贯穿于整个 API 生态,如 API 的设计、编写 API 文档、测试和部署。 Swagger 是一种通用的,和编程语言无关的 API 描述规范。
本文首发于《创建API服务最小只要4行代码!!!尝新体验ASP.NET Core 6预览版本中的最小Web API(minimal APIS)新特性》
这里还是先简单介绍下mall项目吧,mall项目是一套基于 SpringBoot + Vue + uni-app 实现的电商系统(Github标星60K),采用Docker容器化部署。包括前台商城项目和后台管理系统,能支持完整的订单流程!涵盖商品、订单、购物车、权限、优惠券、会员、支付等功能!
在最早的 JavaWeb 时代的时候,如果想要返回一个页面,你需要一行一行的去 print,如果遇到变量,还需要自己进行字符串的拼接
对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证 API 文档的及时性将有很大的帮助。
我记得在毕业以前,就大致明白这样一件事情,系统之间、模块之间的交互,要确定协议,要定义接口,兜兜转转这些年过去了,我觉得对这件事情认识当然越来越深刻,也说不清其中的程度。最近做的项目中,开始大量地和 OpenAPI 打交道,一方面要最先使用 OpenAPI 来定义接口,让多个其他交互的模块都遵循它来开发,就是 “OpenAPI Driven Development” 的意思,这没啥特别的;但另一方面,系统中还需要把 Protobuf 接口定义转换成 HTTP 接口定义,并实施地使用 swagger-core 来动态创建 OpenAPI Spec,这就比较好玩了。
SpringDoc是一款可以结合SpringBoot使用的API文档生成工具,基于OpenAPI 3,目前在Github上已有1.7K+Star,更新发版还是挺勤快的,是一款更好用的Swagger库!值得一提的是SpringDoc不仅支持Spring WebMvc项目,还可以支持Spring WebFlux项目,甚至Spring Rest和Spring Native项目,总之非常强大,下面是一张SpringDoc的架构图。
在后端项目中,难免遇到需要写接口文档方便第三方调用的场景,一般业界最常用的方案是使用swagger。Java项目中,一般采用springfox项目,它集成了swagger和swagger-ui,不需要单独部署项目,可让文档随着项目一起发布。
开始一个新使用Angular和 ASP.NET Core 的ABP项目最简单的方法就是通过官方的模板页面来生成模板。切记包含zero模块。在官网完成创建和下载你的项目后,跟随后面的步骤来运行你的应用。
在微服务构建的过程中,你也许发现写的那些restful风格的接口需要编写文档。 文档一般包括要输入哪些参数,哪些参数是必填的,哪些是选填的。还有返回结果的格式以及结果示例。 也许你可以通过在git上写markdown文档来做这些事情。 但每个接口对应的文档地址这些对应关系你又需要关心。 通过swagger,这一切你都不需要做了。 在你编写自己的restful接口的时候,只需要添加一些annotation就可为你自动的生成接口文档。你上面的那些内容都为你自动生成。 甚至连简单的功能测试表单都为你做好了。 总
看见就一个目标,我头就大,虽然最后没有getshell,但是获取了大量的敏感信息还有利用漏洞进入后台。
SpringBoot项目整合swagger2需要用到两个依赖:springfox-swagger2和springfox-swagger-ui,用于自动生成swagger文档。
自此一个非常方便又简单的swagger-ui集成好了,写完业务逻辑代码可以立马公布restful api给前端调用。
Swagger官方Starter解决了之前整合Swagger的一系列问题,简化了SpringBoot整合Swagger的过程,使用起来更加方便了。同时对于一些复杂的配置使用基本没有变化,一些之前的使用方式依然可以使用!
如果是使用 git 克隆 swagger-ui,可以在当前项目的public目录下执行如下命令
Our-Task项目致力于打造一个完整的清单管理系统,只是为了把自己每天都安排地明明白白。
由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。
swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具,在前后端开发之前,后端要先出接口文档,前端根据接口文档来进行项目的开发,双方开发结束后在进行联调测试。
松哥最近正在录制 TienChin 项目视频~采用 Spring Boot+Vue3 技术栈,里边会涉及到各种好玩的技术,小伙伴们来和松哥一起做一个完成率超 90% 的项目,戳戳戳这里-->TienChin 项目配套视频来啦。 ---- Swagger 好早之前就更新到 3 了,不过一直没空和小伙伴们分享下具体玩法,主要是也是因为 Swagger 虽然升级了,但是我们在 Spring Boot 中却依然可以使用老版本的 Swagger,不过好像是从 Spring Boot2.6 开始,你会发现用不了老版本的
Automated JSON API documentation for API’s built with Spring
客户端渲染模式下,服务端把渲染的静态文件给到客户端,客户端拿到服务端发送过来的文件自己跑一遍 JS,根据 JS运行结果,生成相应 DOM,然后渲染给用户。
顾翔老师开发的bugreport2script开源了,希望大家多提建议。文件在https://github.com/xianggu625/bug2testscript,
Swagger:The Best APIs are Built with Swagger Tools 。Swagger可以定义一个标准的RESTful风格的API,与语言无关,是一个API的规范。
领取专属 10元无门槛券
手把手带您无忧上云