V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
爱意满满的作品展示区。
shisang
V2EX  ›  分享创造

辞职了有些空余时间,做了一个自动 PHP 自动生成 swagger 文档工具,零代码入侵。

  •  
  •   shisang · 2018-05-29 13:38:28 +08:00 · 2442 次点击
    这是一个创建于 2399 天前的主题,其中的信息可能已经有所发展或是发生改变。

    看一些自动生成 swagger 文档的工具,都是要在注释写一些特定的语法,本人有洁癖很难接受写一大坨奇怪语法的东西在注释里边,干脆就撸了一个自动生成 swagger 文档的工具,基于 php-parser语法树构建文档结构。

    生成文档样例

    文档详情:

    https://github.com/eclogue/knight/tree/master/docs

    github 项目

    写得有些糙,目前 manjusaka 只针对courser 自动生成文档。manjusaka 会把大的 swagger 文档拆成若干个小的部分, 手动写过 swagger 文档的人应该知道一旦 api 接口过百,如果是单一个 yaml 文件大几千行,看一下就头疼更别说让人改。

    小弟不才如果做得不对,欢迎大神斧正或者贡献代码。

    因为是零入侵,所以不可能做的完美,有些地方还需要自己手动改,但已经节省了很大工作(准确的说需要定义 200 response 数据结构和 tag,security )。

    入口文件:

    ---
    swagger: '2.0'
    
    ################################################################################
    #                              API Information                                 #
    ################################################################################
    info:
      version: v0.1.1
      title: knight API
      description: |
        这是 knight 自动生成 API,仅限供参考。api 采用 rest 风格,正常情况下 response statusCode
        20x 为成功的返回,
        40x 为客户端错误,
        50x 为服务端错误,
        20x 返回 格式为 { message: 'OK', data: ... }
        非 20x 返回 { message: '错误描述', code: '详细请看 api 错误码'}
    ################################################################################
    #                  Host, Base Path, Schemes and Content Types                  #
    ################################################################################
    host: localhost
    basePath: /
    schemes:
      - http
    produces:
      - application/json
    consumes:
      - application/json
      - multipart/form-data
    tags:
      - name: Auth
        description: 认证
      - name: Users
        description: 用户
    paths:
      $ref: ./routers/index.yaml
    definitions:
      $ref: ./definitions/index.yaml
    
    
    
    目前尚无回复
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   946 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 22ms · UTC 22:49 · PVG 06:49 · LAX 14:49 · JFK 17:49
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.