Swagger使用笔记

栏目: 服务器 · 发布时间: 6年前

内容简介:Swagger使用笔记

He who has a "why" to live for can bear almost any "how" --尼采

Swagger使用笔记

前言

此前一直在关注swagger,不过也一直处于看看案例,读读文档的状态。关于写api接口文档和mock的事,多次头疼,看了许多 工具 都不甚满意,最近在使用 Mock ( 在线体验 )的时候

发现它在文档里写道:

支持同步 Swagger 文档,1秒便能生成 Mock 数据。之后接口文档更新也能通过更新操作重新生成 Mock 数据

这太强大了,心动不已。

我自己很喜欢 easy-mock 这个工具,但写REST api的时候,感觉重复数据声明太多,很不爽,我们知道post/put的大部分属性是相同的,而get/post也有大量重复的属性。如何能以一种更加方便的方式在easy-mock(其他的mock工具也一样)定义接口,以便于更好地做到 DRY , Swagger是绝佳的解决方案,而且它能带给你的远不止于此

why的问题一解决,how to do 只是细节问题了

于是重新花了2个晚上的时间,集中地读了文档,也动手写了几个demo,很符合预期

接下来以经典的3w问题为线索来记录下我的学习过程

Swagger是什么

关于swagger是什么的问题,swagger的首页说的再清楚不过:

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

因为swagger庞大的生态系统,我们在api的整个生命周期中都能从中受益: from design and documentation, to test and deployment

前头我的easy-mock属于test部分,同时它也有效地帮助前后端分离

如果你想对Swagger有更深的了解,可以看下对Tony Tam的这段采访(Tony Tam影响了Swagger的诞生): 通过Swagger进行API设计,与Tony Tam的一次对话

OpenAPI Specification

上述这段引用中有一个名词值得一提: OpenAPI Specification(OAS) ,它本身开放在 OpenAPI-Specification ,它的目的是:

The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs

为何需要用它

如果你在为一个系统设计API,你希望更好的管理你的API,你希望有一个工具能一站式地解决API相关的所有事情,从设计到文档再到mock,甚至能直接从设计文档中生成代码(声明式编程),这确实是可能的,如果你的描述信息是完备的,自动化生成mock接口以及具体语言(诸如swagger支持flask等十几种框架)实现在理论上都可行

这些便是你选择Swagger的理由

how to do...

最后便是怎么做的问题,这反而不太难,在互联网高度发达的今天,海量的资料遍布网络

我接下来把我的学习过程和资料做个笔记,希望对你有用

起步

尽管Swagger本身是开源的,你可以自行搭建整个工具链,但从在线工具开始尝试,会让你更快接触核心的东西,而不是在搭建工具上忙活半天

我们从 swaggerhub 开始

Swagger使用笔记

swaggerhub是个非常棒的项目,你在这里可以:

  • 在线编辑你的API文档(用的是 swagger-editor )
    • 可使用使用json或yaml来书写(设计)你的API,推荐yaml,对人类更友好(无论是书写、阅读还是添加注释)
    • 可导出为json或是yaml,easy-mock中要求json文档的url,所以你可以把导出的json放到 github gist ,然后贴到easy-mock里,之后就自动生成mock接口了
    • 可直接生成可运行20几种server代码(诸如flask),当然也能自动生成client可执行代码
  • swaggerhub自带了mock插件,可以直接在线测试,UI页里有curl的请求例子
  • 和github相似,你可以分享以及fork别人的API项目: search ,这样对学习很有帮助
  • 你可以邀请你的团队成员一起来编辑

上边的截图是官方的demo: Swagger Petstore ,这是一个很完整的API项目(同时也比较复杂),我们可以一边试运行,一边做些修改看看每个参数的作用,如果你想对swagger的语法有个整体的认识,推荐这篇文档 Swagger从入门到精通

我的做法是先通读一遍(粗读)上边的文档,之后对着别人的API项目学习,遇到不懂的去查阅这个文档

另外文档结尾处有个彩蛋: OpenAPI Specification Visual Documentation ,这是查阅swagger写作语法的神器

如何把握Swagger

Swagger生态极其庞大,各种工具层出不穷,如何确定一个清晰工作流。而不会在庞大的生态链里迷失

我觉得核心是理解:Swagger的生态系统是围绕Swagger文档(json/yaml)构建的,就是说我们书写的纯文本(json/yaml)便是我们输出的所有东西,它是全息的,我们手里只需有这个纯文本,就能做所有事情,此外的工具都是围绕它构建的,把这个纯文本导入到响应的工具里,就可获得其他功能,诸如漂亮的UI,自动化的mock等等

你熟悉markdown的话,你会发现他们在设计思路上有不少相似点

编写API文档,其实我们只是在写一个简单的纯文本文件。你可以用任何你喜欢的文本编辑器来写(vim/emacs/atom/vscode/sublime)。但是为了提高效率,建议选择Swagger Editor(swaggerhub默认是它),诸如语法检查之类的功能能帮你省下大量排错的时间

一个小案例

学习一个新技术,我喜欢用它写一个简单的blog,我们接下来试试用swagger来写博客文章的API,我们假设Article有四个属性:

  • userid
  • title
  • content
  • tag

API是RESTful风格(可以参考我此前的文章RESTful-Api),支持:

  • get /articles : 获取文章列表
  • post /articles : 新建一篇文章(登录用户)
  • put /articles/<id> : 更新某篇的文章(指定文章id)
  • delete /articles/<id> : 删除某篇的文章
  • get /articles/search?title=python : 搜索文章

下边是它的api描述

swagger: "2.0"
info:
  version: 1.0.0
  title: blog
  # description支持markdown
  description: |
    # blog API documentation

    这篇文档描述了的blog(article)的api接口

# host: localhost:8000 #localhost blog 
# basePath: /api
schemes:
  - https
  - http
consumes:
  - application/json
produces:
  - application/json

paths:
  /:
    get:
      summary: Service root
      description: 列出所有api的描述信息.
      operationId: root
      responses:
        '200':
          description: Success
      security: []
  /articles:
    get: 
      summary: list all articles
      operationId: list_all_articles #后端函数
      responses:
        '200':
          #todo
          description: Annotation successfully created
          schema:
            $ref: '#/definitions/ArticleList'
        '400':
          description: Could not create article from your request
          schema:
            $ref: '#/definitions/Error'

    post:
      summary: Create a new Article
      operationId: createArticle
      parameters:
        - name: Article
          in: body
          description: article to be created
          required: true
          schema:
            $ref: '#/definitions/NewArticle'
      responses:
        '200':
          description: article successfully created
          schema:
            $ref: '#/definitions/Article'
        '400':
          description: Could not create article from your request
          schema:
            $ref: '#/definitions/Error'
  /articles/{id}:
    get:
      summary: Fetch an Article
      operationId: fetchArticle
      parameters:
        - name: id
          in: path
          description: ID of article to return
          required: true
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Article'
        '404':
          description: article not found or no permission to view
          schema:
            $ref: '#/definitions/Error'
    patch:
      summary: Update an Article
      description: |
        This endpoint is available under both the `PATCH` and `PUT`
        request methods. Both endpoints have PATCH-characteristics
        as defined in [RFC5789](https://tools.ietf.org/html/rfc5789#section-1),
        meaning the request body does not have to include the whole Article
        object.

        New implementations should use the `PATCH` request method, and existing
        implementations continue to work under `PUT` but should switch to `PATCH`.

      operationId: updateArticle
      parameters:
        - name: id
          in: path
          description: ID of article to return
          required: true
          type: string
        - name: Article
          in: body
          description: Updated article body
          required: true
          schema:
            $ref: '#/definitions/NewArticle'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Article'
        '400':
          description: Could not create article from your request
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: article not found or no permission to update
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete an Article
      operationId: deleteArticle
      parameters:
        - name: id
          in: path
          description: ID of article to return
          required: true
          type: string
      responses:
        '200':
          description: Success
          schema:
            type: object
            required:
              - deleted
              - id
            properties:
              deleted:
                type: boolean
                enum:
                  - true
              id:
                type: string
        '404':
          description: article not found or no permission to delete
          schema:
            $ref: '#/definitions/Error'

  /search:
    get:
      summary: Search for annotations
      operationId: search #后台对应的函数名
      parameters:
        - name: limit
          in: query
          description: The maximum number of annotations to return.
          required: false
          type: integer
          minimum: 0
          maximum: 200
          default: 20
        - name: offset
          in: query
          description: >
            The minimum number of initial annotations to skip. This is
            used for pagination.
          required: false
          type: integer
          default: 0
          minimum: 0
        - name: sort
          in: query
          description: The field by which annotations should be sorted.
          required: false
          type: string
          default: updated
      responses:
        '200':
          description: Search results
          schema:
            $ref: '#/definitions/SearchResults'

definitions:
  NewArticle:
    # todo json 2 yaml: https://www.json2yaml.com/
    # 也可以是在线的
    #$ref: './schemas/annotation-schema.json' #https://h.readthedocs.io/en/latest/api/schemas/annotation-schema.json 
    type: object
    properties:
      userid:
        type: string
        #"pattern": "^acct:.+$"
      title:
        type: string
      content:
        type: string
      tags:
        type: array
        items:
          type: string
  Article:
    allOf:
      - $ref: '#/definitions/NewArticle' # NewArticle属性展开在这里
      - required:
        - id
        properties:
          id:
            type: string
  Error:
    type: object
    required:
      - status
    properties:
      status:
        type: string
        enum:
          - failure
      reason:
        type: string
        description: A human-readable description of the reason(s) for failure.
  SearchResults:
    #用作list
    type: object
    required:
      - rows
      - total
    properties:
      rows:
        type: array
        items:
          $ref: '#/definitions/Article'
      total:
        description: Total number of results matching query.
        type: integer
  ArticleList:
    #用作list
    type: object
    required:
      - rows
      - total
    properties:
      rows:
        type: array
        items:
          $ref: '#/definitions/Article'
      total:
        description: Total number of results matching query.
        type: integer
# Added by API Auto Mocking Plugin
host: virtserver.swaggerhub.com
basePath: /pwnote/blog/1.0.0

如果你对其中的语法有所不解可以查阅: Swagger从入门到精通

我同时做了以下工作:

围绕Swagger的生态

可以在github上搜swagger,会发现有许多相关项目,我列出几个我恰好看到或关注的

django-rest-swagger

Django REST Framework 是写api的神器

配合 django-rest-swagger 更是如虎添翼

ReDoc

我最近在使用的一个是 ReDoc ,有不少有名的项目在用它作为api文档的展示工具:


以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网

标签: swagger

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

结网

结网

王坚 / 人民邮电出版社 / 2010-12-10 / 59.00元

本书以如何创建、发布、推广互联网产品为主线,介绍了互联网产品经理的工作内容以及应对每一部分工作所需的方法和工具。为用户创造价值是产品经理的第一要务,产品经理的工作是围绕用户及具体任务展开的,本书丰富的案例和透彻的分析道出了从发现用户到最终满足用户这一过程背后的玄机。 本书面向现在正在从事及未来将要从事互联网相关工作的创业者和产品经理,也可以作为互联网产品策划人员或相关专业学生的参考书。新版完......一起来看看 《结网》 这本书的介绍吧!

HTML 压缩/解压工具
HTML 压缩/解压工具

在线压缩/解压 HTML 代码

RGB CMYK 转换工具
RGB CMYK 转换工具

RGB CMYK 互转工具

HEX HSV 转换工具
HEX HSV 转换工具

HEX HSV 互换工具