如何编写基于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. unbuntu更换软件源

    编辑/etc/apt/sources.list文件,将文件中原有的国外源全部注释掉,文件头添加以下内容 ##中科大源 deb https://mirrors.ustc.edu.cn/ubuntu/ b ...

  2. appium---uiautomator定位方法

    前面总结了7种定位方法,今天在介绍一种uiautomator方法,其实appium就是基于uiautomator框架实现的,让我们一起看下uiautomator有哪些定位方法可以使用 uiautoma ...

  3. 无法添加符号: 归档没有索引;运行 ranlib 以添加一个

    这将告诉您对象文件的格式.如果对象文件是针对不同的平台编译的,则会导致无法为存档创建索引.要纠正这种情况,您需要重新编译这些文件.

  4. 智能指针类模板(中)——Qt中的智能指针

    Qt中的智能指针-QPointer .当其指向的对象被销毁时,它会被自动置空 .析构时不会自动销毁所指向的对象-QSharedPointer .引用计数型智能指针 .可以被自由的拷贝和赋值 .当引用计 ...

  5. Appium左右、上下滑动(Java)

    网上很多文章都说用swipe来左右滑动,你把代码一贴,结果报错,看半天,原来是java-client中swipe早就被废除了!!!下面介绍一种Java写法来左右上下滑动: 首先,创建一个Swipe类 ...

  6. day55_9_19模型层的操作

    一.配置settings. 如果是queryset对象 那么可以点query直接查看该queryset的内部sql语句 将以下代码放入settings中.就可以实现当使用orm时查看sql语句: LO ...

  7. 创建testng.xml文件

    简单介绍 运行TestNG测试脚本有两种方式:一种是直接通过IDE运行(例如使用eclipse中的“Run TestNG tests”),另一种是从命令行运行(通过使用xml配置文件).当我们想执行某 ...

  8. jQuery中的工具(十)

    1. jQuery.each(object, [callback]), 通用遍历方法,可用于遍历对象和数组 不同于遍历 jQuery 对象的 $().each() 方法,此方法可用于遍历任何对象.回调 ...

  9. CF-1175 B.Catch Overflow!

    题目大意:有一个初始变量,值为0,三种操作 for x 一个循环的开始,循环x次 end 一个循环的结束 add 将变量值加一 问最后变量的值是否超过2^32-1,若超过,输出一串字符,不超过则输出变 ...

  10. 修改官方发行openstack镜像的cloud-init登录方式为账号密码登录

    openstack使用的镜像多为qcow2格式,各个发行商也开源了针对openstack制作的镜像.但是这些镜像的登录方式都是注入用户名和密码的方式,就是说不能够直接通过账号和密码登录.那么如何将一个 ...