文章目录
- 一、swagger 本地部署
- 1、安装 nodejs、npm
- 2、npm 安装 http server
- 3、下载项目
- 4、环境变量
- 5、运行hs服务
- 二、Swagger 使用
- 三、关于
一、swagger 本地部署
Swagger Editor 可以使用在线编辑器，也可以离线本地部署环境。使用YAML定义接口规范，接口文档生成不同框架服务端、客户端。可以导出JSON格式API规范，通过Swagger UI发布。
1、安装 nodejs、npm
npm是Nodejs的包管理器
戳node.js官网
戳node.js文档
2、npm 安装 http server
npm install -g http-server
..\npm\下生成http-server、hs
..\npm\node_modules下生成http-server
3、下载项目
Swagger-Editor GitHub项目
4、环境变量
拷贝hs.cmd的绝对路径C:\Users\Administrator\AppData\Roaming\npm（npm安装hs的目录）作为HS_HOME环境变量
5、运行hs服务
命令行 cd 到 Swagger-Editor 项目下载存放目录，运行命令 hs ，默认端口8080；也可指定端口 hs -p 8081；Ctrl+C 可以停止服务运行
二、Swagger 使用
-
建议使用Firefox/Google Chrome访问 http://127.0.0.1:8080
-
YAML格式字段，附：yaml语法
swagger: '2.0' # swagger版本 info: title: 文档标题 description: 描述 version: "v1.0" # 版本号 termsOfService: "" # 服务截止日期 contact: # 联系 name: "" # 姓名 url: "" # URL email: "" # 邮箱 license: # 授权证书 name: "" # 名称，如Apache 2.0 url: "" # URL host: api.xxx.net # 域名，可包含端口，默认提供yaml文件的host basePath: / # 前缀 schemes: # 传输协议 - http - https securityDefinitions: # 安全设置 api_key: type: apiKey name: Authorization # 实际变量名，如Authorization in: header # 变量放哪里，query或header OauthSecurity: # oauth2 type: oauth2 flow: accessCode # 可选implicit/password/application/accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' scopes: admin: Admin scope user: User scope media: Media scope auth: type: oauth2 description: "" # 描述 authorizationUrl: http://haofly.net/api/oauth/ name: Authorization # 实际变量名，如Authorization tokenUrl: flow: implicit # 认证形式，implicit/password/application/accessCode scopes: write:post: 修改文件 read:post: 读取文章 security: # 全局安全设置 auth: - write:pets - read:pets consumes: # 接收MIME types列表 - application/json # 接收响应Content-Type - application/vnd.github.v3+json produces: # 请求MIME types列表 - application/vnd.knight.v1+json # 请求头Accept值 - text/plain; charset=utf-8 tags: - name: post description: 关于post的接口 externalDocs: description: find more info here url: https://haofly.net paths: # 接口url详细信息 /projects/{projectName}: # 接口后缀，可定义参数 get: tags: # 所属分类的列表 - post summary: 接口描述 # 简介 description: # 描述 externalDocs: description: url: operationId: "" # 操作唯一ID consumes: [string] # 可接收的mime type列表 produces: [string] # 可发送的mime type列表 schemes: [string] # 可接收的协议列表 deprecated: false # 接口是否已经弃用 security: # OAuth2认证 - auth: - write:post - read: read parameters: # 接口参数 - name: projectName # 参数名 in: path # 参数在哪个地方，如path、body、query等 type: string # 参数类型 allowEmptyValue: boolean # 是否允许空值 description: 项目名 # 参数描述 required: true # 是否必须 default: * # 设置默认值 maximum: number # number最大值 exclusiveMaximum: boolean # 是否排除最大的值 minimum: number # number最小值 exclusiveMinimum: boolean maxLength: integer # int最大值 minLength: integer enum: [*] # 枚举值 items: # type为数组时可定义其项目类型 - $ref: "#/parameters/uuidParam" responses: # 设置响应 200: # 通过http状态描述响应 description: Success # 响应描述 schema: # 返回数据的结构 $ref: '#/definitions/ProjectDataResponse' # 关联至某个model /another: # 另一个接口 responses: 200: description: schema: type: object properitis: data: $ref: '#/definitions/User' # 关联 definitions: # Model/Response的定义 Product: # 定义一个model type: object # model类型 properties: # 字段列表 product_id: # 字段名 type: integer # 字段类型 description: # 字段描述 product_name: type: string description: ProjectDataResponse: type: object properties: data: $ref: '#/definitions/ProjectResponse' # model之间关联，表示data字段里包含的是一个ProjectResponse对象 parameters: # 接口使用的params limitParam: name: limit in: query description: max records to return required: true type: integer format: int32 responses: # 接口使用的responses NotFound: description: Entity not found.
三、关于
博主CSDN@崔同学原创码字不易，喜欢记得点赞收藏支持哦 😃
