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
  • https://pypi.org/project/flask-swagger/

原文 

https://jiajunhuang.com/articles/2019_04_01-swagger_i_dislike.md.html

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » Swagger? 不好用

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址