文档书写(Document)

2020-11-05  by  

概述

用于编写接口文档,通过命令生成,在线的,可测试,可交付的技术文档。

可独立使用

环境要求

Symfony 4 +

启用社区食谱

打开项目中composer.json文件,将

"extra": {
   "symfony": {
       "allow-contrib": false,
       "require": "4.4.*"
   }
}

替换为

"extra": {
  "symfony": {
      "allow-contrib": true,
       "require": "4.4.*",
  }
}

安装

composer require phpzlc/document-bundle

文档配置

  1. 配置接口主机域名

    配置位置

    .env.local

    配置

    DOC_HOST=http://dome-api.com
    
  2. 配置文档全局内容

    配置位置

    src/Document/Config.php

    配置项

    标题, 出版商, 说明, 注意, 附录。

生成文档

  1. 命令

    php bin/console phpzlc:generate:document
    
  2. 生成文件位置

    public/apidoc

  3. 访问文档

    {host}/public/apidoc/index.html
    
  4. 效果

    首页

    首页

    前要页

    概要

    数据字典页

    数据字典

    接口详情页

    接口详情

    Debug页

    Debug

书写文档

  1. 书写位置

    src/Document

  2. 工作原理

    命令执行之后会扫描 src/Document 下所有后缀为 Document 的类文件中后缀为 Action 的方法。

  3. 文档目录构建规范

    src/Controller 下的目录类结构保持一致即可。

  4. 代码示例

    namespace App\Document\Api;
       
    use PHPZlc\Document\Document;
       
    class ApiDocument extends Document
    {
        public function add()
        {
            $this->addParam('platform', '平台', 'string', false, 'applets');
       
            return parent::add();
        }
       
        public function setUrl($url)
        {
            return parent::setUrl('/api' . $url);
        }
    }
    
     namespace App\Document\Api;
        
     class AuthDocument extends ApiDocument
     {
         public function add()
         {
             $this->setGroup('登录模块');
             parent::add();
             return $this;
         }
        
         public function setUrl($url)
         {
             parent::setUrl('/auth'.$url);
             return $this;
         }
        
         public function phoneLoginAction()
         {
             $this->add()
                 ->setTitle('手机号登录')
                 ->setUrl('/phone-login')
                 ->setMethod('post')
                 ->addParam('phone', '手机号')
                 ->addParam('password', '密码')
                 ->setReturn(
                     <<<EOF
     <pre>
     "{
         "code": 0,
         "msg": "登录成功",
         "msgInfo": [],
         "data": []
     }"
     "{
         "code": 1,
         "msg": "常规错误",
         "msgInfo": [],
         "data": []
     }"
     </pre>
     EOF
        
                 )
                 ->generate();
         }
    

找到错别字了?本文档有什么问题么?分叉并编辑 它 !

CJayhe

谢谢您的赞赏~

使用微信扫描二维码完成支付

抱歉弹框打扰,系统检测到您今日累计浏览时长已达120秒。如果我们的项目对您有帮助,在 关闭窗口之前,希望能够阅读弹框内容,帮助我们变得更好。

一个成功的项目,实现功能只是基础,合理的架构,对资源的调度能力才是灵魂。 PHPZlc, 致力于在Symfony的基础上提供“知行合一”的项目开发方案。

如果您有关切问题和好的想法:

提交

如果您想帮助我们,可以为我们点亮星星,也可以提供资金支持。

您还可以通过以下渠道,关注我们,获取最新的框架动态,帮助项目获取人气,扩大影响力。

开源伙伴招募:https://phpzlc.com/blog/11.html

由于我们无法获取您是否已经是我们的会员了,所以此弹框每日都会弹出一次,关闭