如何编写基于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. pushgateway

    下载pushgateway wget https://github.com/prometheus/pushgateway/releases/download/v0.9.0/pushgateway-0. ...

  2. 28道java基础面试题-下

    28道java基础面试题下 15.Java语言如何进行异常处理,关键字:throws.throw.try.catch.finally分别如何使用? 答:Java通过面向对象的方法进行异常处理,把各种不 ...

  3. URL、URI、URN之间的区别

    URL统一资源定位符 URI统一资源标识符 URN统一资源名称 URL是URI的一个特例. URI由URL和URN两部分组成. 在java类中,URI类不包含任何访问资源的方法,它唯一的作用就是解析. ...

  4. 工具资源系列之 github 上各式各样的小徽章从何而来?

    前言 平时大家在在逛 github 时或多或少都看到过项目首页各式各样的小徽章,不知道你是否和我一样好奇这些小徽章都是哪来的呢? 首先我们先来一睹为快目前前端开发的三大主流框架: var ,看一看他们 ...

  5. 2019 SDN上机第4次作业

    1. 解压安装OpenDayLight控制器(本次实验统一使用Beryllium版本) 配置java环境 安装OpenDayLight控制器 2. 启动并安装插件 cd distribution-ka ...

  6. http状态码大全(404、505、502,500)

    HTTP 400 – 请求无效HTTP 401.1 – 未授权:登录失败HTTP 401.2 – 未授权:服务器配置问题导致登录失败HTTP 401.3 – ACL 禁止访问资源HTTP 401.4 ...

  7. POJ-2661Factstone Benchmark

    Factstone Benchmark Time Limit: 1000MS   Memory Limit: 65536K Total Submissions: 5577   Accepted: 25 ...

  8. 全链路跟踪TraceId

    数据库主键:标示唯一一条数据,譬如唯一商品,唯一订单 全局事务ID:实现分布式事务一致性的必备良药 请求ID:requestId,seesionId,标示一个请求或者一次会话的生命周期 身份证ID:代 ...

  9. Neo4j 第十二篇:使用Python驱动访问Neo4j

    neo4j官方驱动支持Python语言,驱动程序主要包含Driver类型和Session类型.Driver对象包含Neo4j数据库的详细信息,包括主机url.安全验证等配置,还管理着连接池(Conne ...

  10. Filco圣手二代双模蓝牙机械键盘连接方法

    转自:https://www.cnblogs.com/goldenSky/p/11437780.html 常规方法 确认键盘的电源接通. 同时按下「Ctrl」+「Alt」+「Fn」执行装置切换模式.配 ...