Swagger? 不好用

最近用了一下swagger,swagger是一个用于把代码和文档连接起来的工具,我们在注释里写好一些东西,然后swagger生成出一个网页, 这样可以方便的在网页上点一下测试,就可以发出一个请求。但是,实际体验中,并不好用,原因如下:

  • 文档虽然可以自动生成,但是书写相当繁琐
  • 虽然可以在网页上自动生成一个用例用于测试,但是参数意义、是否可选等不明确

例如Python的Flask-Swagger使用如下:

class UserAPI(MethodView):
    def post(self):
        """
        Create a new user
        ---
        tags:
          - users
        definitions:
          - schema:
              id: Group
              properties:
                name:
                 type: string
                 description: the group's name
        parameters:
          - in: body
            name: body
            schema:
              id: User
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  description: email for user
                name:
                  type: string
                  description: name for user
                address:
                  description: address for user
                  schema:
                    id: Address
                    properties:
                      street:
                        type: string
                      state:
                        type: string
                      country:
                        type: string
                      postalcode:
                        type: string
                groups:
                  type: array
                  description: list of groups
                  items:
                    $ref: "#/definitions/Group"
        responses:
          201:
            description: User created
        """
        return {}

我更倾向于:

  • 使用Postman发请求
  • 单独使用Markdown写API


更多文章
  • Redis源码阅读与分析二:双链表
  • Redis源码阅读与分析三:哈希表
  • Redis源码阅读与分析一:sds
  • Golang runtime 源码阅读与分析
  • Golang的一些坑
  • GC 垃圾回收
  • 设计一个路由
  • Go语言性能优化实战
  • 那些年开发的时候踩过的坑
  • (关系型)数据库优化总结
  • 动态规划民科教程
  • Golang 分布式异步任务队列 Machinery 教程
  • 使用geohash完成地理距离计算
  • 2018年就要到了,这一年都做了什么呢?
  • 算法导论阅读笔记 --- 排序算法