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


微信公众号
关注公众号,获得及时更新

更多文章
  • 高性能MySQL笔记第一章
  • 面试的一些技巧
  • HTTP/2 简介
  • 独立运营博客一年的一些数据分享
  • To B(usiness) 和 To C(ustomer)
  • 常见的软件架构套路
  • Cookie 中的secure和httponly属性
  • Google Ads使用体验
  • Go的custom import path
  • 如何挖掘二级子域名?
  • Go Module 简明教程
  • 写了一个Telegram Bot:自动化分享高质量内容
  • ArchLinux 怎么降级 package ?
  • Vim打开很慢,怎么找出最慢的插件?怎么解决?
  • 为什么我选择放弃运营微信公众号?