一 。openapi介绍
OpenAPI的前身是swagger规范。Swagger是一套有助于前后端分离,接口管理和测试工具集
SwaggerTM是一个用于描述和文档化RESTful接口的项目。
Swagger规范定义了一系列的文件,用以描述API。这些文件可以被Swagger-UI项目用于展示API,也可以被Swagger-Codegen项目用于生成代码。一些其他的工具也可以利用这些文件,例如测试工具soapui。
规划文件格式:
格式是遵循JSON格式的。YAML作为JSON的一个超集,也是被支持的。
有关于field,有两种:
第一种是fixed fields,是说field的名称是固定的;
第二种是Patterned fields,field的名字不是固定的,而是使用正则表达式匹配。
filed名称大小写敏感
文件结构
Swagger的规范要求将API用一个单一的文件表示。不过,定义可以拆成多个文件。使用$ref将他们拼合在一起。这符合JSON Schema规范。
按照惯例,Swagger规范文件命名为swagger.json。
Swagger文件根元素(具体节点描述参考官网https://swagger.io/docs/specification/basic-structure/)
名称 | 类型 | 描述 |
---|---|---|
swagger | string | 必填。值必须为“2.0” |
info | Info对象 | 必填。提供有关于API的元数据。 |
host | string | host地址,域名或者是ip。可以包含端口,但不得包含其他路径 |
basePath | string | 必须以”/”开头,定义基础路径。不支持路径模板 |
schemes | string数组 | 定义传输协议,必须从以下选择:http、https、ws、wss 。如果不指定schemes,默认的scheme就是访问Swagger时访问的协议 |
consumes | string数组 | 定义一系列可以被消费的MIME类型。 |
produces | string数组 | 定义一系列可以被生产的MIME类型。 |
paths | Paths对象 | 必填。可获得的paths和操作符。 |
definitions | Definitions对象 | 持有通过操作生产和消费的数据类型 |
parameters | Parameters Definitions对象 | 持有操作时使用的参数。 |
responses | Responses Definitions对象 | 持有操作的结果。 |
securityDefinitions | Security Definitions对象 | 安全策略 |
security | Security Definitions对象数组 | 整体安全策略 |
tags | Tag对象数组 | 标签 |
externalDocs | External Documentation对象 | 添加外部文档 |
使用springfox集成swagger 参考(https://github.com/springfox/springfox) 点击文档可进入
http://springfox.github.io/springfox/docs/current/
二。 openapi工具集swagger
swagger是围绕openapi规范构建的一组开源工具,可以帮助您设计、构建、记录和使用RESTAPI。
主要的swagger工具包括:
- swagger编辑器--基于浏览器的编辑器,您可以在其中编写openapi规范。
- swagger UI--将openapi规范呈现为交互式API文档(界面展示openapi规范文件 更清晰明了)。
- swagger codegen--从openapi规范生成服务器存根和客户机库。
1. 安装swagger编辑器
编辑器可以编辑openapi规范文件 预览ui效果等 安装过程参考 (https://swagger.io/docs/swagger-tools/#swagger-editor-documentation-0)
准备服务器 centos7 ip 192.168.58.144
swagger编辑器 需要nodejs环境支持
yum -y install epel-release.noarch yum -y install nodejs npm
安装swagger编辑器
yum -y install openssl openssl-devel wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip unzip swagger-editor.zip http-server swagger-editor
启动后使用浏览器访问
http://192.168.58.144:8080/#/
界面出现可以左侧便捷openapi 右侧ui方式显示 菜单项 Generate Server可以生成不同环境下的服务器代码 也可以生成调用的客户端代码
ui是可以直接通过读取openapi文档来直接可视化api
官网文档提供的是2.X版本安装 3.X版本 直接解压即可用 不过没找到汉化的方式 这里就安装官方文档安装2.X吧
文档地址:https://swagger.io/docs/swagger-tools/
github地址:https://github.com/swagger-api/swagger-ui(这是3.X)
3.X代码下文档有提供2.X代码地址 https://github.com/swagger-api/swagger-ui/tree/2.x
下载zip代码包
解压后目录 swagger-ui-2.x\dist 就是ui的目录 进入dist目录 双击index.html可以单击使用 也可以服务器部署使用
cd swagger-ui-2.x\dist && http-server -p8888访问地址
http://192.168.58.144:8888/
界面效果为(默认有个openapi的json 可以点击explore预览ui效果):、
打开index.html文件 将js的以下两行放开 将js替换成 zh-cn.js
<!-- Some basic translations --> <script src='lang/translator.js' type='text/javascript'></script> <script src='lang/zh-cn.js' type='text/javascript'></script>
汉化后的界面是
三 。springfox集成 swagger
springboot使用springfox集成swagger2(http://springfox.github.io/springfox/docs/current/#springfox-support-for-jsr-303)
添加maven依赖
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>cn.et</groupId> <artifactId>springfox</artifactId> <version>0.0.1-SNAPSHOT</version> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.0.RELEASE</version> </parent> <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.8.0</version> </dependency> <dependency> <groupId>io.springfox.ui</groupId> <artifactId>springfox-swagger-ui-rfc6570</artifactId> <version>1.0.0</version> </dependency> </dependencies> </project>
添加main方法测试
package springfox; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.context.annotation.Bean; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.ResponseBody; import io.swagger.annotations.ApiOperation; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger.web.DocExpansion; import springfox.documentation.swagger.web.ModelRendering; import springfox.documentation.swagger.web.OperationsSorter; import springfox.documentation.swagger.web.TagsSorter; import springfox.documentation.swagger.web.UiConfiguration; import springfox.documentation.swagger.web.UiConfigurationBuilder; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Controller @EnableAutoConfiguration @EnableSwagger2 public class RestController { @ApiOperation(value = "helloworld方法", notes = "${RestController.home}") @RequestMapping(value="/",method=RequestMethod.GET) @ResponseBody String home() { return "Hello World!"; } public static void main(String[] args) throws Exception { SpringApplication.run(RestController.class, args); } @Bean public Docket petApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() .pathMapping("/"); } @Bean UiConfiguration uiConfig() { return UiConfigurationBuilder.builder() .deepLinking(true) .displayOperationId(false) .defaultModelsExpandDepth(1) .defaultModelExpandDepth(1) .defaultModelRendering(ModelRendering.EXAMPLE) .displayRequestDuration(false) .docExpansion(DocExpansion.NONE) .filter(false) .maxDisplayedTags(null) .operationsSorter(OperationsSorter.ALPHA) .showExtensions(false) .tagsSorter(TagsSorter.ALPHA) .validatorUrl(null) .build(); } }
其他api注解参考 官网 访问swagger-ui界面(http://localhost:8080/swagger-ui.html#/rest-controller)