swagger - RESTFUL接口文档在线自动生成、代码自动生成工具详解
swagger - RESTFUL接口文档在线自动生成、代码自动生成工具详解
如需转载请标明出处:http://blog.csdn.net/itas109
QQ技术交流群:129518033
文章目录
- swagger - RESTFUL接口文档在线自动生成、代码自动生成工具详解
- 前言
- 1. RESTful API规范
- 2. swagger editor生成swagger配置文件
- 2.1 swagger editor使用
- 2.2 `swagger editor`地址
- 3. swagger-codegen生成代码(以服务端为例)
- 3.1 swagger-codegen简介
- 3.2 swagger-codegen生成代码(以NodeJS服务端为例)
- 3.3 swagger-codegen地址
- 4. swagger-ui
- 4.1 swagger-ui简介
- 4.2 swagger-ui使用
- 4.3 swagger-ui地址
环境:
nodejs : 12.13.0
swagger-editor : 3.15.8(2021-03-04)
swagger-codegen : 2.4.9(2019-10-14)
swagger-ui : 3.44.1(2021-03-04)
完整源码:
https://github.com/itas109/node-webdev
https://github.com/itas109/node-webdev/tree/main/code/1.webFramework/2.swaggerhttps://gitee.com/itas109/node-webdev
https://gitee.com/itas109/node-webdev/tree/main/code/1.webFramework/2.swagger
前言
Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
1. RESTful API规范
swagger使用swagger 2.0(2014-09-08) 规范,其依赖于openapi 3.0版本的规范。
openapi 规范,是定义一个标准的、与具体编程语言无关的RESTful API的规范。官方文档(中文):OpenAPI 开放API规范
swagger 2.0规范示例:
swagger: '2.0' # 语义化版本号规范
info: # 【必选】API相关的元数据title: Swagger Demo # 【必选】应用的名称version: 1.0.0 # 【必选】版本信息description: # 描述Swagger Demo - https://github.com/itas109/node-webdevtermsOfService: # 服务条款的URL地址https://github.com/itas109/node-webdevcontact: # 联系人信息name: itas109email: itas109@qq.comlicense: # 协议name: MIT Licenseurl: https://opensource.org/licenses/mit/
host: # 服务端host127.0.0.1:8080
basePath: # url基路径/v1
tags: # 元数据的一系列标签- name: userdescription: Operations about userexternalDocs:description: user external docsurl: https://github.com/itas109
schemes: # 协议,http,https,ws,wss- http- https
externalDocs: # 附加的文档description: external docsurl: https://github.com/itas109
paths: # 【必选】API有效的路径和操作/user/login: # 端点的相对路径,路径必须以 / 打头get:tags: # 标签分类- usersummary: Logs user into the systemdescription: ''produces:- application/json- application/xmlparameters: # 参数 - name: username # 【必选】参数的名称in: query # 【参数】 入参类型,query, header, path 或 cookiedescription: user name for login # 描述required: true # 是否必须type: string- name: passwordin: querydescription: user password for loginrequired: truetype: stringresponses: # 【必须】返回值'200':description: json, {"code":0,"message":"success","data":[{"token_type":"bearer","access_token":"adcc4dc09a4f9ac278d019605f00f33c9a08e0e3","expires_in":3600,"refresh_token":"418470a87cb3d9320a092bb550790ae2c13182f1"}]}schema:$ref: '#/definitions/ApiResponse'headers:X-Rate-Limit:type: integerformat: int32description: calls per hour allowed by the userX-Expires-After:type: stringformat: date-timedescription: date in UTC when token expires'400':description: Invalid username/passwordschema:$ref: '#/definitions/ApiErrorResponse''/user/{username}':get:tags:- usersummary: Get user by user namedescription: ''produces:- application/json- application/xmlparameters:- name: usernamein: pathdescription: The name that needs to be fetchedrequired: truetype: stringresponses:'200':description: successful operationschema:$ref: '#/definitions/ApiResponse''400':description: Invalid username suppliedschema:$ref: '#/definitions/ApiErrorResponse''404':description: User not foundschema:$ref: '#/definitions/ApiErrorResponse'security:- user_auth:- 'write:user'- 'read:user'- token: []- BasicAuth: []
securityDefinitions: # 安全定义user_auth:type: oauth2authorizationUrl: localhost:8080/oauth/tokenflow: implicitscopes:'write:user': modify user in your account'read:user': read your usertoken:type: apiKeyname: Authorizationdescription: "Authorization: Bearer xxx"in: headerBasicAuth:type: basic
definitions:ApiResponse:example: {"code":0, "message":"success","data":[{'xxx':'xxx'}]}type: objectproperties:code:type: integerformat: int32description: "System Level Code:\n 0 success \n 100101 system inner error \n 100201 interface maintenance \n 200202 interface disabled \n\n Service Level Code:\n 200101 input params empty \n 200102 input params error \n 200103 no auth"message:type: stringdescription: "code details information"data:type: stringdescription: "return datas array when code equal 0"ApiErrorResponse:example: {"code":200102, "message":"input params error"}type: objectproperties:code:type: integerformat: int32description: "System Level Code:\n 0 success \n 100101 system inner error \n 100201 interface maintenance \n 200202 interface disabled \n\n Service Level Code:\n 200101 input params empty \n 200102 input params error \n 200103 no auth"message:type: stringdescription: "code details information"
2. swagger editor生成swagger配置文件
上节中对RESTful API规范
做了介绍,本节介绍使用swagger editor
进行可视化的生成RESTful API
的yaml或json文件。
2.1 swagger editor使用
在swagger editor
的左边可以进行接口定义,右边可以实时看到对应的api信息。
最后,点击顶部的菜单栏File -> Save as YAML
生成yaml文件。
2.2 swagger editor
地址
https://github.com/swagger-api/swagger-editor
https://github.com/swagger-api/swagger-editor/archive/v3.15.8.tar.gz
在线编辑:http://editor.swagger.io
本地编辑:
git clone https://github.com/swagger-api/swagger-editor.git && cd swagger-editor
双击index.html在浏览器中打开
+--- swagger-editor
| +--- dist
| | +--- swagger-editor-bundle.js
| | +--- swagger-editor-standalone-preset.js
| | +--- swagger-editor.css
| | +--- swagger-editor.js
| +--- index.html
3. swagger-codegen生成代码(以服务端为例)
经过上节我们可以生成RESTful API
的yaml文件,本节介绍如何通过yaml文件生成代码(这里以NodeJS服务端为例)。
3.1 swagger-codegen简介
swagger-codegen是OpenAPI (f.k.a Swagger) 规范的开源代码生成器,支持 API 客户端, API 服务单和 API 文档。
- 客户端 : ActionScript , Ada , Apex , Bash , C# , C++ , Clojure , Dart , Elixir , Elm , Eiffel , Erlang , Go , Groovy , Haskell , Java , Kotlin , Lua , Node.js , Objective-C , Perl , PHP , PowerShell , Python , R , Ruby , Rust , Scala , Swift , Typescript
- 服务端 : Ada , C# , C++ , Erlang , Go , Haskell , Java , Kotlin , PHP , Python , NodeJS , Ruby , Rust , Scala
- API文档 : HTML , Confluence Wiki
- 配置文件 : Apache2
- 其他 : JMeter
3.2 swagger-codegen生成代码(以NodeJS服务端为例)
- 查看swagger-codegen支持语言
$ java -jar swagger-codegen-cli-2.4.9.jar langsAvailable languages: [ada, ada-server, akka-scala, android, apache2, apex, aspnetcore, bash, csharp, clojure, cwiki, cpprest, csharp-dotnet2, dart, dart-jaguar, elixir, elm, eiffel, erlang-client, erlang-server, finch, flash, python-flask, go, go-server, groovy, haskell-http-client, haskell, jmeter, jaxrs-cxf-client, jaxrs-cxf, java, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs, msf4j, java-pkmst, java-play-framework, jaxrs-resteasy-eap, jaxrs-resteasy, javascript, javascript-closure-angular, java-vertx, kotlin, lua, lumen, nancyfx, nodejs-server, objc, perl, php, powershell, pistache-server, python, qt5cpp, r, rails5, restbed, ruby, rust, rust-server, scala, scala-gatling, scala-lagom-server, scalatra, scalaz, php-silex, sinatra, slim, spring, dynamic-html, html2, html, swagger, swagger-yaml, swift4, swift3, swift, php-symfony, tizen, typescript-aurelia, typescript-angular, typescript-inversify, typescript-angularjs, typescript-fetch, typescript-jquery, typescript-node, undertow, ze-ph, kotlin-server]
- 查看swagger-codegen的生成代码帮助信息
java -jar swagger-codegen-cli-2.4.9.jar help generate
生成nodejs服务端代码
generate主要参数:
-i swagger restful api文件的路径,url或本地文件
-l 生成客户端代码的语言,该参数为必须
-o 生成文件的位置(默认当前目录)
java -jar swagger-codegen-cli-2.4.9.jar generate -i swagger.yaml -l nodejs-server -o samples
+--- samples
| +--- .swagger-codegen
| | +--- VERSION
| +--- .swagger-codegen-ignore
| +--- api
| | +--- swagger.yaml
| +--- controllers
| | +--- User.js
| +--- index.js
| +--- package.json
| +--- README.md
| +--- service
| | +--- UserService.js
| +--- utils
| | +--- writer.js
3.3 swagger-codegen地址
+--- swagger-codegen
| +--- gen.bat
| +--- gen.sh
| +--- swagger.yaml
| +--- swagger-codegen-cli-2.4.9.jar
https://github.com/swagger-api/swagger-codegen
https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.9/swagger-codegen-cli-2.4.9.jar
java Version 8 Update 271 (2020-10-20)
https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html
4. swagger-ui
4.1 swagger-ui简介
上节中的swagger-codegen生成的nodejs-server代码运行后也可以查看在线API文档。
本节中的swagger-ui是无依赖
的在线API文档,其仅包含HTML、JS和CSS。
4.2 swagger-ui使用
+--- swagger-ui
| +--- favicon-16x16.png
| +--- favicon-32x32.png
| +--- index.html
| +--- swagger-ui-bundle.js
| +--- swagger-ui-standalone-preset.js
| +--- swagger-ui.css
| +--- swagger-ui.js
index.html修改
SwaggerUIBundle({"url": "swagger.yaml", // 本文件相同目录下的本地文件,也可以为远程文件"validatorUrl": false, // 不校验
})
运行
cd swagger-ui
http-server -p 8080
4.3 swagger-ui地址
https://github.com/swagger-api/swagger-ui
https://github.com/swagger-api/swagger-ui/archive/v3.44.1.tar.gz
License
License under CC BY-NC-ND 4.0: 署名-非商业使用-禁止演绎
如需转载请标明出处:http://blog.csdn.net/itas109
QQ技术交流群:129518033
Refrence:
- https://swagger.io/specification/
- https://github.com/fishead/OpenAPI-Specification
swagger - RESTFUL接口文档在线自动生成、代码自动生成工具详解相关推荐
- Swagger+Spring mvc生成Restful接口文档
2019独角兽企业重金招聘Python工程师标准>>> Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端 ...
- Swagger:搭建Swagger API接口文档
文章目录 Swagger 1.1导语: 1.2 Swagger是什么?它能干什么? 1.3Swagger简介 1.4 Swaggerr特点: SpringBoot 集成Swagger 1. 导包 2. ...
- 根据接口文档中的入参,生成自动化测试用例中的异常测试用例,包含用例描述,用例数据
根据接口文档中的入参,生成自动化测试用例中的异常测试用例,包含用例描述,用例数据 参考文章: (1)根据接口文档中的入参,生成自动化测试用例中的异常测试用例,包含用例描述,用例数据 (2)https: ...
- oracle web API,在Web API程序中使用Swagger做接口文档
#### 创建Web API程序 在VS2019中创建一个ASP.NET Web应用程序,选择Web API来创建RESTful的HTTP服务项目,构选MVC和Web API核心引用. #### 安装 ...
- restful 接口文档_第 16 篇:别再手动管理接口文档了
作者:HelloGitHub-追梦人物 大多数情况下,开发的接口都不是给开发这个接口的人用的,所以如果没有接口文档,别人就无法有哪些接口可以调用,即使知道了接口的 URL,也很难知道接口需要哪些参数, ...
- Popular MVC框架swagger+knif4j接口文档工具使用示例
Popular MVC框架swagger接口文档工具使用示例 简介 此项目介绍如何使用popularmvc内置的swagger+knife4j实现简单易用的实时API文档,支持在线调试接口! 此项目只 ...
- 在.Net Core中使用Swagger制作接口文档
在实际开发过程中后台开发人员与前端(移动端)接口的交流会很频繁.所以需要一个简单的接口文档让双方可以快速定位到问题所在. Swagger可以当接口调试工具也可以作为简单的接口文档使用. 在传统的asp ...
- 推荐一款接口文档在线管理系统-MinDoc
项目简介 MinDoc 是一款针对IT团队开发的简单好用的文档管理系统. MinDoc 的前身是 SmartWiki 文档系统.SmartWiki 是基于 PHP 框架 laravel 开发的一款文档 ...
- 访问swagger/Knife4j 接口文档报错:java.lang.NumberFormatException: For input string: ““
目录 问题描述 解决过程 问题描述 报异常如下:java.lang.NumberFormatException: For input string: "" 虽然不影响使用,但是每次 ...
- MinDoc 接口文档在线管理系统
MinDoc 是一款针对IT团队开发的简单好用的文档管理系统. MinDoc 的前身是 SmartWiki 文档系统.SmartWiki 是基于 PHP 框架 laravel 开发的一款文档管理系统. ...
最新文章
- web项目中的web.xml元素解析
- DAPP(分布式应用),区块链新物种,程序员掘金新风口!
- 推荐一个小巧轻便的RSS阅读器
- 第四范式推出业界首个基于持久内存、支持毫秒级恢复的万亿维线上预估系统...
- Oracle 根据一张发票的供应商,取供应商所有符合条件的发票的总额
- 内存泄漏和内存溢出的优化
- 前端学习(3020):vue+element今日头条管理--创建路由和配置路由
- *由易到难的讲解动态规划(精)
- linux磁盘满了怎么处理
- 免费下载百度文库需下载券文件
- 计算机老丢失运行库,计算机中丢失api-ms-win-crt-runtime-l1-1-0.dll的修复方案
- app推送-极光推送
- Java-Preferences用法-入门
- 《自顶向下计算机网络》其二 Application Layer
- 运维信息系统 (Devops Information System)开发日志
- 实用!7个强大的Python机器学习库!⛵
- Java设计模式 -11- 外观模式(Facade模式)
- word添加参考文献和标注的详细简单方法
- 对论文写作专栏文章的简单归纳总结和心得体会
- d3.js——多柱体柱状图(v5)