如何编写基于OpenAPI规范的API文档

简介

  • Swagger
  • Swagger是一个简单但功能强大的API表达工具。支持的语言种类繁多
  • 使用Swagger生成API,我们可以得到交互式文档,自动生成代码的SDK以及API的发现特性
  • OpenAPI规范
  • OpenAPI规范是Linux基金会的一个项目,试图定义一种用来描述API格式或API定义的语言,来规范RESTful服务的开发过程
  • OpenAPI可以帮助我们描述一个API的基本信息:
    • 有关API的一般性描述
    • 可用路径
    • 在每个路径上的可用操作
    • 每个操作的输入输出格式
  • OpenAPI规范这类API定义语言能够更简单、快速的表述API,尤其是在API设计阶段作用比较明显
  • 如何编写API文档
  • 编辑器采用在线编辑:https://editor.swagger.io/#
  •       swagger: "2.0"
    info:
    description:
    version: "1.0.0"
    title: "Swagger Petstore"
    termsOfService: "http://swagger.io/terms/"
    contact:
    email: "apiteam@swagger.io"
    license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
    host: "petstore.swagger.io"
    basePath: "/v2"
    tags:
    - name: "pet"
    description: "Everything about your Pets"
    externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
    - name: "store"
    description: "Access to Petstore orders"
    - name: "user"
    description: "Operations about user"
    externalDocs:
    description: "Find out more about our store"
    url: "http://swagger.io"
    schemes:
    - "http"
    paths:
    /pet:
    post:
    tags:
    - "pet"
    summary: "Add a new pet to the store"
    description: ""
    operationId: "addPet"
    consumes:
    - "application/json"
    - "application/xml"
    produces:
    - "application/xml"
    - "application/json"
    parameters:
    - in: "body"
    name: "body"
    description: "Pet object that needs to be added to the store"
    required: true
    schema:
    $ref: "#/definitions/Pet"
    responses:
    405:
    description: "Invalid input"
    security:
    - petstore_auth:
    - "write:pets"
    - "read:pets"

从零开始

  •   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation schemes:
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    {}
  • 显示界面如下:
  • 首先要通过swagger属性来声明OpenAPI规范的版本
  • 然后需要说明API文档的相关信息,比如API文档版本、API文档名称、描述信息等
  • 最后作为webURL,一个很重要的信息就是用来给消费者使用的 根URL ,可以使用协议http或https、主机名、根路径来描述:
        schemes:
    - https
    host: simple.api
    basePath: /openapi101
    ```
  • 接下来就是写API的操作,通过paths,然而这里没有写只是通过{}对象占用位置
  •   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation schemes:
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons:
    get:
    summary: Get some persons
    description: Returns a list containing all persons
    responses:
    200:
    description: A list of Person
    schema:
    type: array
    items:
    required:
    - username
    properties:
    firstname:
    type: string
    lastname:
    type: string
    username:
    type: string
  • 在上面的这些代码中,做了以下的动作:
    1. 添加了/persons的路径,用来访问一组用户信息
    2. 在路径中添加了HTTP方法get,同时也有一些简单的描述信息summary和description
    3. 定义响应类型responses,响应类型中添加了HTTP状态码200
    4. 定义了响应内容:通过响应消息中的schema属性来描述清楚具体的返回内容。通过type属性可知一组用户信息就是一个用户信息数组,每一个数组元素则是一个用户对象,该对象包含三个string类型的属性,其中username必须提供(required)
  • 定义请求参数
  •   paths:
    /persons:
    get:
    summary: Get some persons
    description: Returns a list containing all persons
    parameters:
    - name: pageSize
    in: query
    description: Number of persons returned
    type: integer
    - name: pageNumber
    in: query
    description: Page number
    type: integer
  • 首先在get方法中添加了一个parameters属性
  • 在参数列表中,添加了两个参数pageSize和pageNumber的整形参数,并有简单描述
  • 定义路径参数
  •   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation schemes:
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons/{username}:
    get:
    summary: Get some persons
    description: Returns a list containing all persons
    parameters:
    - name: username
    in: path
    required: true
    description: The person's username
    type: string responses:
    200:
    description: A list of Person
    schema:
    type: array
    items:
    required:
    - username
    properties:
    firstname:
    type: string
    lastname:
    type: string
    username:
    type: string
  • 路径参数、请求参数以及消息参数等的不同之处就在于in属性的值不同,分别为path、query、body等。同时对于参数的类型可以使用type或者schema来定义,例如消息体参数如下:
  •   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation schemes:
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons:
    post:
    summary: Creates a person
    description: Adds a new person to the persons list
    parameters:
    - name: person
    in: body
    description: The person to create
    schema:
    required:
    - username
    properties:
    firstname:
    type: string
    lastname:
    type: string
    username:
    type: string
    responses:
    200:
    description: OK
  • 如果是单个参数可以使用type进行定义例如integer,string ,array等,而如果是json类型的参数就需要使用schema类来定义。
  • 定义相应消息
  •   response:
    204:
    description:Persons successfully created
    400:
    description:Persons couldn't have been created
  • 简化数据模型
  • 通过使用definition来定义可重用的对象。如下:
  •   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation schemes:
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons:
    post:
    summary: Creates a person
    description: Adds a new person to the persons list
    parameters:
    - name: person
    in: body
    description: The person to create
    schema:
    $ref: '#/definitions/Person'
    responses:
    200:
    description: OK
    schema:
    $ref: "#/definitions/Person" definitions:
    Person:
    required:
    - username
    properties:
    firstname:
    type: string
    lastname:
    type: string
    username:
    type: string
  • 定义可重用的参数
  •   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation schemes:
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons/{username}:
    get:
    parameters:
    - $ref: '#/parameters/username' responses:
    200:
    description: fsafsf parameters:
    username:
    name: username
    in: path
    required: true
    description: The person's username
    type: string

高级定义

  • 字符串的长度和格式
  •   -   name: username
    in: path
    required: true
    description: fasfsa
    type: string
    pattern: "[a-z0-9]{8,64}"
    minLength: 8
    maxLength: 64
  • 日期和时间
  •   parameters:
    - name: dateofBirth
    in: query
    description: fasfsaf
    type: string
    format: date
  • 枚举类型
  •   code:
    type: string
    enum:
    - DBERR
    - NTERR
    - UNERR
  • 高级参数
  • 参数的媒体类型
  • 在文档的根节点下面添加:
  •   produces:
    - text/xml
    consumes:
    - application/json
    - application/xml
  • 高级响应消息
  • 要定义一个不带消息体的相应消息,只需要写响应状态和描述即可
  •   responses:
    '204':
    description: Person successfully created
  • 与请求消息类似,必带参数使用required来标识
  •   Person:
    required:
    - username
    properties:
    firstname:
    type: string
    lastname:
    type: string
    username:
    type: string
  • 分类标签
  • tags: - Persons

Swagger从入门到放弃的更多相关文章

  1. CYQ.Data 从入门到放弃ORM系列:开篇:自动化框架编程思维

    前言: 随着CYQ.Data 开始回归免费使用之后,发现用户的情绪越来越激动,为了保持这持续的激动性,让我有了开源的念头. 同时,由于框架经过这5-6年来的不断演进,以前发的早期教程已经太落后了,包括 ...

  2. [精品书单] C#/.NET 学习之路——从入门到放弃

    C#/.NET 学习之路--从入门到放弃 此系列只包含 C#/CLR 学习,不包含应用框架(ASP.NET , WPF , WCF 等)及架构设计学习书籍和资料. C# 入门 <C# 本质论&g ...

  3. OpenStack从入门到放弃

    OpenStack从入门到放弃 目录: 为何选择云计算/云计算之前遇到的问题 什么是云计算 云服务模式 云应用形式 传统应用与云感知应用 openstack及其相关组件介绍 flat/vlan/gre ...

  4. 绕过校园网的共享限制 win10搭建VPN服务器实现--从入门到放弃

    一.开篇立论= =.. 上次说到博主在电脑上搭建了代理服务器来绕过天翼客户端的共享限制,然而经过实际测试还不够完美,所以本着生命不息,折腾不止的精神,我又开始研究搭建vpn服务器= =... (上次的 ...

  5. 《区块链:从入门到放弃》之obc安装步骤

    obc安装步骤 朋友们可能会好奇,厨师不研究菜谱怎么改研究兵法了,哈哈,我原本是app出身,最近被安排去预研区块链和比特币技术,2个月下来,颇有斩获.期间得到IBM的CC同学指导我一步一步安装obc的 ...

  6. win10搭建代理服务器实现绕过校园网的共享限制--从入门到放弃

    博主所在学校特别坑爹,校园网被电信一家垄断了,而且最恶心的还是电信要求一条网线只能供一台电脑上网,不许接路由器共享网络= =- (还有电信2M价格是380+每年,20m是500每年,而且网速都很慢= ...

  7. WPF从入门到放弃系列第二章 XAML

    本文是作者学习WPF从入门到放弃过程中的一些总结,主要内容都是对学习过程中拜读的文章的整理归纳. 参考资料 XAML 概述 (WPF):https://msdn.microsoft.com/zh-cn ...

  8. Android -- 带你从源码角度领悟Dagger2入门到放弃

    1,以前的博客也写了两篇关于Dagger2,但是感觉自己使用的时候还是云里雾里的,更不谈各位来看博客的同学了,所以今天打算和大家再一次的入坑试试,最后一次了,保证最后一次了. 2,接入项目 在项目的G ...

  9. Android -- 带你从源码角度领悟Dagger2入门到放弃(二)

    1,接着我们上一篇继续介绍,在上一篇我们介绍了简单的@Inject和@Component的结合使用,现在我们继续以老师和学生的例子,我们知道学生上课的时候都会有书籍来辅助听课,先来看看我们之前的Stu ...

随机推荐

  1. Shell命令-网络操作之基础之telnet、ssh

    文件及内容处理 - telnet.ssh 1. telnet:使用TELNET协议远程登录 telnet命令的功能说明 telnet 命令用于远端登入.执行 telnet 指令开启终端机阶段作业,并登 ...

  2. C学习笔记(5)--- 指针第二部分,字符串,结构体。

    1. 函数指针(function pointer): 函数指针是指向函数的指针变量. 通常我们说的指针变量是指向一个整型.字符型或数组等变量,而函数指针是指向函数. 函数指针可以像一般函数一样,用于调 ...

  3. 用pip命令把python包安装到指定目录

    sudo pip install transforms3d --target=/usr/local/lib/python2.7/site-packages pip install transforms ...

  4. UVA11464 Even Parity 搜索+递推

    问题描述 UVA11464 题解 第一直觉爆搜. 发现 \(N \le 15\) ,然后后面每行都可以通过第一行递推出来. 爆搜第一行,递推后面+check \(\mathrm{Code}\) #in ...

  5. luoguP4097 [HEOI2013]Segment

    题意 李超树板子题. 对每个区间维护该区间中点\(mid\)的最优线段. 插入一个线段: 求出这个线段的斜率和截距,注意特判无斜率的情况,得到\(y=kx+b\). 之后开始在线段树上插入,假设当前节 ...

  6. yii2-CaptchaAction macos500 不显示

    把公司一个项目pull到本地 发现验证码不输出了 怀疑是gd库没装  php -m看了下 gd库是装了的 有搜索到可能是因为自带的php拓展生成不了png(觉得不太可能) 试了下自己写一个图片生成pn ...

  7. ant design pro解决初始加载,有顺序的请求/请求顺序报错问题/登录后再加载其他数据/异步的顺序问题/偷跑

    方法是:如在Authorized.jsx中解决,当未登录成功(包括登录失败和登录验证中),就显示loading,否则继续 加载渲染children 一个三目运算或者if分支就可以解决,但是要写到最先加 ...

  8. windows上安装python和python开发工具

    一.python安装: 登录python官网,下载需要的安装包:https://www.python.org/downloads/windows/.,一般就下载 executable installe ...

  9. windows端口转发工具(LCX)

    端口转发(Port forwarding),有时被叫做隧道,是安全壳(SSH) 为网络安全通信使用的一种方法.端口转发是转发一个网络端口从一个网络节点到另一个网络节点的行为,其使一个外部用户从外部经过 ...

  10. 微信小程序跳转web-vie时提示appId无法读取:Cannot read property 'appId' of undefined

    微信小程序报web-view错无法读取appId:Cannot read property 'appId' of undefined 问题描述: 我以前一直如下写代码没报错也都是可以使用的,并且小程序 ...