SwaggerEditor:如何编写RESTful API文档

Posted chszs

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了SwaggerEditor:如何编写RESTful API文档相关的知识,希望对你有一定的参考价值。

SwaggerEditor:如何编写RESTful API文档

  • 2019.12.17

一、概述

Swagger/OpenAPI规范的目标是为RESTful API的开发定义一个标准的,与语言无关的接口。使用浏览器打开Swagger Editor在线编辑器,就可以按照OpenAPI v3.0.2规范开始编写RESTful API文档了。

1.1、格式

遵循OpenAPI规范的OpenAPI文档本身就是一个JSON对象,可以用JSON格式或YAML格式表示。描述RESTful API的文件可以保存为.json、.yaml、.yml格式。

1.2、数据类型

OpenAPI规范定义定义的数据类型有:

原始类型类型格式说明
integerintegerint32带符号32位整数
longintegerint64带符号64位整数(长整型)
floatnumberfloat浮点数类型
doublenumberdouble双精度浮点数类型
stringstring字符串类型
bytestringbyteBASE64编码的字符
binarystringbinary任意八位字节的序列
booleanboolean
datestringdateRFC-3339规范的full-date定义
dateTimestringdate-timeRFC-3339规范的date-time定义
passwordstringpasswordUI提示隐藏输入

二、API写法说明

1、第一级标签

可以把OpenAPI文档看成是一个树形结构,第一级的标签有:

  • openapi:文档对象,定义文档采用的规范的版本
  • info:定义了该API文档相关的元数据信息
  • externalDocs:定义文档可以引用的外部资源,以便扩展文档。
  • servers:定义实现了API文档的服务器资源
  • tags:定义要CRUD操作的资源对象
  • paths:定义资源端点的路由路径,以及对资源端点可用的操作,是API文档最重要的内容。
  • components:定义了OpenAPI规范文档中使用的一套可重用的、针对不同方面的对象。

2、第二级标签:components

  • schemas:用于定义输入和输出的数据类型。这些类型可以是对象,还可以是原始类型或数组类型。
  • securitySchemas:定义API操作所使用的安全模式。支持的安全模式有HTTP身份认证、API key(可以作为HTTP头部的内容,或者Cookie参数,或作为查询参数)、OAuth2’s common flows等。

schemas细节

  • 实体Bean名/HTTP资源名(首字母大写)
    • type:类型,通常是object
    • properties:属性/成员字段
      • 属性名/成员字段名
        • type:使用(1.2、数据类型),比如integer
        • format:使用(1.2、数据类型),比如int64
        • description:描述,通常省略,关键内容才加上
        • default:默认值

3、第二级标签:paths

  • 请求的资源路径,也即接口,比如’/folders/folderId’

    • get:请求的HTTP方法,还可以是post、put、delete
    • tags:接口标签,可以有多个
    • summary: 接口简介,不能超过120个字符
    • description:接口描述,支持Markdown语法
    • operationId:操作的ID,全局唯一的接口标识,通常使用Java对应的方法名
    • parameters:参数列表
      • in:参数从何处来。必填。取值仅限: “query”, “header”, “path”, “formData”, “body”
      • name:参数名。
      • description:参数描述
      • required:参数是否必须。通过路径传参(in取值"path")时reqquired值为true
      • schema:
        • type:参数类型。取值仅限: “string”, “number”, “integer”, “boolean”, “array”, “file”
        • format:参数格式,如"int64"
    • requestBody:请求主体
      • description:请求主体描述
      • content:
      • application/json:请求的内容类型,也可能是application/x-www-form-urlencoded
        • schema:
          • properties:
            • name:
              • type:类型
              • description:描述
    • responses: 描述来自API操作的响应
      • 响应状态码,比如’404’
        • description: 响应描述
        • content: 内容

以上是关于SwaggerEditor:如何编写RESTful API文档的主要内容,如果未能解决你的问题,请参考以下文章

SwaggerEditor基本使用

如何使用 ThinkJS 优雅的编写 RESTful API

如何借助 Django 来编写一个 Python restful api接口

如何借助 Django 来编写一个 Python restful api接口

如何借助 Django 来编写一个 Python restful api接口

如何借助 Django 来编写一个 Python restful api接口