-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
api 文档优化 #53
Comments
使用 OpenAPI 3..x.x 来书写 api 文档, 因为本来对 2.x.x 也不熟, 所以使用最新版本 |
示例openapi: 3.0.0
info:
title: 图床系统
version: v1
description: >
[tuchuang.space](https://tuchuang.space) 的 RESTful API 文档
contact:
name: Jiang-Xuan
url: https://github.com/Jiang-Xuan
email: 645762213@qq.com
servers:
- url: https://beta.tuchuang.space/api/v1
description: beta 环境的 api
- url: https://tuchuang.space/api/v1
description: 生产环境的 api
tags:
- name: depercated
description: 被弃用的 api, 当前可用, 会在下一个版本的 api 中被移除
- name: image
description: 关于图片的操作
paths:
/images:
post:
tags:
- image
summary: 上传图片, 创建一个/多个 image 实例
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
images:
type: array
items:
type: string
format: binary
responses:
200:
description: 图床实例创建成功, 也就是图片上传成功
content:
application/json:
schema:
type: object
properties:
images:
type: object
properties:
<图片的原始命名>:
$ref: "#/components/schemas/Image"
422:
description: images 参数缺失
content:
application/json:
schema:
type: object
properties:
errorMsg:
type: string
example:
errorMsg: 'images 参数缺失'
delete:
tags:
- image
summary: 永久删除该系统中的某张图片
requestBody:
content:
application/json:
schema:
type: object
properties:
key:
type: string
description: 移除图片的 key
required:
- key
example:
key: 'c60ec1670dca7c13615b89eaca7d9a4f:c5b6a8374c30faf4c32b86f76699605acbda3f8f6ef7b137d3e563deba1dd7228e44287e0aa5042e6116428066384504'
responses:
200:
description: 删除成功
400:
description: 请求的 content-type 不正确
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: 'Body should be a JSON object'
422:
description: 请求的参数 缺失/类型错误
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: array
items:
type: object
properties:
field:
type: string
code:
type: string
example:
message: 'Validation Failed'
errors:
- field: 'key'
type: 'missing_field'
404:
description: 该系统中不存在该图片
components:
schemas:
Image:
type: object
properties:
cdnPath:
type: string
description: 图片的 CDN 访问地址
ext:
type: string
description: 图片的扩展名
fileName:
type: string
description: 图片被处理之后的命名, 全局唯一
originName:
type: string
description: 图片的原始命名, 也就是上传的时候的图片的名称
md5:
type: string
description: 图片的 MD5 哈希值
deleteKey:
type: string
description: 图片的删除 key, 传递给删除图片的接口来永久的从系统中移除该图片
mimetype:
type: string
description: 图片的 mimetype
externalDocs:
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types
example:
cdnPath: https://i.tuchuang.space/b674825d3b110165ebfdf276c7b376b5.png
ext: .png
fileName: 169640a6f82fbc6278cc4b6e39040764.png
originName: download.png
md5: 6109872bbf8069d187b60b3ee04b375b
deleteKey: 277c9845f2ed779bdedff0d78cbd3654:5f69789d8d58e64cbe0ad1c8c46e8f6efea692de502cd6da5e328909c9b644e4b81a7871c443995b53b7787a52a7d201
mimetype: image/png
可以将上面的 yaml 复制到 这里 来预览 api 文档 |
This comment has been minimized.
This comment has been minimized.
swagger-api/swagger-ui#4600 swagger ui 对于 OAS3 的多文件上传有 bug, 等待 swagger-ui 修复 |
根据 OAI/OpenAPI-Specification#1937, https://tools.ietf.org/html/rfc7231#section-4.3.1 GET, DELETE, HEAD 方法的 body 没有明确的语义, 不应该使用, 在 OAS3.0.2 中已经禁止了 DELETE 方法拥有 requestBody 属性
但是在后续的 OAS3.x 会允许 body, 但是不鼓励使用 OAI/OpenAPI-Specification#1937 目前该系统移除图片的 DELTE 接口只支持的是 body 传移除的 key, 这不应该支持, 但是已经支持, 后续 @deprecated 该方式传参, 使用 url param 传参, 或者是通过 url 片段传参 |
非常值得一读的关于 cache 的 issue, OAI/OpenAPI-Specification#1801 (comment) 绝对可以成为一篇文章的 issue |
swagger-ui 不是响应式的设计, 不过目前也没有找到一个比较好的响应式的文档工具, 就使用 swagger-ui, 可以考虑后续将 api doc 页面单独拆出来成为一个非响应式的页面 |
api 文档是很重要的一个资源, 不过目前的 api 文档好像很丑陋, 重构这一块的样式.
swagger 的文档好像很好看, 可以试一试用 swagger 用作 mock 和 文档工具怎么样
The text was updated successfully, but these errors were encountered: