标签：领域 语法规则 head 没有 tor 额外 items 条件 运用
随着互联网技术的发展,前后端技术在各自的道路上越走越远,他们之间的唯一联系变成了api接口,api接口文档编程了前后端人员的纽带,而swagger就是书写api文档的一款框架.
相关资源下载地址: https://download.csdn.net/download/zhixingwu/12008773
推荐: 也可以使用 showdoc来书写api文档. 官网: https://www.showdoc.cc/
全局安装http-server(http-server是一个简单的零配置命令行http服务器)
npm install ‐g http‐server
启动swagger-editor
http‐server swagger‐editor
浏览器打开： http://localhost:8080
| 字段名 | 类型 | 描述 |
|---|---|---|
| swagger | string | 必需的。使用指定的规范版本 |
| info | info Object | 必需的。提供元数据API |
| host | string | 主机名或ip服务API |
| basePath | string | API的基本路径 |
| schemes | [string] | API的传输协议。 值必须从列表中:"http","https","ws","wss"。 |
| consumes | [string] | 一个MIME类型的api可以使用列表。值必须是所描述的Mime类型 |
| produces | [string] | MIME类型的api可以产生的列表。 值必须是所描述的Mime类型 |
| paths | 路径对象 | 必需的。可用的路径和操作的API |
| definitions | 定义对象 | 一个对象数据类型生产和使用操作 |
| parameters | 参数定义对象 | 一个对象来保存参数,可以使用在操作。 这个属性不为所有操作定义全局参数。 |
| responses | 反应定义对象 | 一个对象响应,可以跨操作使用。 这个属性不为所有操作定义全球响应 |
| externalDocs | 外部文档对象 | 额外的外部文档 |
| summary | string | 什么操作的一个简短的总结。 最大swagger-ui可读性,这一领域应小于120个字符 |
| description | string | 解释操作的行为 |
| operationId | string | 独特的字符串用于识别操作。 id必须是唯一的在所有业务中所描述的API。 工具和库可以使用operationId来唯一地标识一个操作,因此,建议遵循通用的编程的命名约定 |
| deprecated | boolean | 声明该操作被弃用。 使用声明的操作应该没有。 默认值是false |
| 普通名字 | type | format | 说明 |
|---|---|---|---|
| integer | integer | int32 | 签署了32位 |
| long | integer | int64 | 签署了64位 |
| float | number | float | |
| double | number | double | |
| string | string | ||
| byte | string | byte | base64编码的字符 |
| binary | stirng | binary | 任何的八位字节序列 |
| boolean | boolean | ||
| date | string | date | 所定义的full-date- - - - - -RFC3339 |
| datetime | string | date-time | 所定义的date-time- - - - - -RFC3339 |
| password | stirng | password | 用来提示用户界面输入需要模糊 |
swagger: '2.0'
info:
version: "1.0.0"
title: 基础模块-城市API
host: api.pcloud.com
basePath: /base
paths:
/city:
post:
summary: 新增城市
parameters:
-
name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 返回城市列表
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityListResponse'
/city/{cityId}:
put:
summary: 修改城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
delete:
summary: 根据ID删除城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 根据ID查询城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityResponse'
/city/search:
post:
summary: 根据条件查询城市列表
parameters:
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityListResponse'
/city/search/{page}/{size}:
post:
summary: 城市分页列表
parameters:
- name: page
in: path
description: 页码
required: true
type: integer
format: int32
- name: size
in: path
description: 页大小
required: true
type: integer
format: int32
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityPageResponse'
definitions:
City:
type: object
properties:
id:
type: string
description: ID
name:
type: string
description: 城市名称
ishot:
type: string
description: 是否热门
ApiResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
ApiCityResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/City'
CityList:
type: array
items:
$ref: '#/definitions/City'
ApiCityListResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/CityList'
ApiCityPageResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
properties:
total:
type: integer
format: int32
rows:
$ref: '#/definitions/CityList' 使用<<黑马程序员代码生成器>>自动生成所有标的yml文档,自动生成的文档中类型均为string ，我们这里需要再对类型进行修改即可.
步骤：
（1）执行建表脚本
（2）使用《黑马程序员代码生成器》生成脚本(HeimaCodeUtil_V2.4_64.zip)
SwaggerUI是用来展示Swagger文档的界面，以下为安装步骤
（1）在本地安装nginx
（2）下载SwaggerUI源码 https://swagger.io/download-swagger-ui/
（3）解压，将dist文件夹下的全部文件拷贝至 nginx的html目录
（4）启动nginx
（5）浏览器打开页面 http://localhost即可看到文档页面
（6）将编写好的yml文件也拷贝至nginx的html目录，这样我们就可以加载我们的swagger文档了
标签：领域 语法规则 head 没有 tor 额外 items 条件 运用
原文地址：https://www.cnblogs.com/itzlg/p/11966754.html
