yii2 使用apidoc生成技术文档

技巧库 · fecommerce · 于 1年前 发布 · 1391 次阅读

原文链接:yii2 使用apidoc生成技术文档

yii2 的apidoc生成文档还是蛮好用的。 首先说一下这个玩意是干什么的,就是用来生成技术文档,效果可以查看:http://www.fecshop.com/doc/fecshop-guide/cn-1.0/guide-index.html#

1.需要安装yii2,参看文章: Yii2 – 安装高级模板 advanced project template

2.然后安装doc 插件

2.1在安装的yii2根目录下面执行:

composer require --prefer-dist yiisoft/yii2-apidoc

2.2或者在composer.json中添加:

    "yiisoft/yii2-apidoc": "~2.1.0"

然后执行:composer update

可能会报错,如果报错,将上面的改成:

    yiisoft/yii2-apidoc": "~2.0.0"

安装成功就可以使用了

3.写md文件

可以看下面的第四部的路径,md文件存放的地址: /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0,那么我们在这个路径下面新建2个比较重要的md文件

README.md 和 index.md

README.md 是左侧菜单部分

index.md 是guide-index.html页面,一般和README.md一样,用来做首页菜单索引,当然也可以添加自己想要的内容

生成的效果可以参看:

http://www.fecshop.com/doc/fecshop-guide/cn-1.0/guide-index.html#

展示一个demo:

README.md:

    FecShop 文档说明
    ===============================
    版权所有。
    2016 (c) FecShop Software LLC。
    目前进度
    -----
    *  [Fecshop 开发进度](fecshop-jindu.md)
    *  [Fecshop 开发LOG](fecshop-jindu-log.md)
    关于与安装
    -----
    *  [Fecshop 关于-架构特点](fecshop-about-fecshop.md)
    *  [Fecshop 关于-功能介绍](fecshop-about-function.md)
    *  [Fecshop 关于-系统结构](fecshop-about-system-contruct.md)
    *  [Fecshop 安装与初始配置](fecshop-install.md)
    Fecshop配置
    -----------
    *  [Fecshop 配置-配置结构](fecshop-init-config-construction.md)
    *  [Fecshop 配置-Yii2配置](fecshop-init-config-yii2.md)
    *  [Fecshop 配置-fecshop配置](fecshop-init-config-advanced.md)

index.md

    FecShop 文档说明
    ===============================
    版权所有。
    2016 (c) FecShop Software LLC。
    关于与安装
    -----
    *  [Fecshop 关于-架构特点](fecshop-about-fecshop.md)
    *  [Fecshop 关于-功能介绍](fecshop-about-function.md)
    *  [Fecshop 关于-系统结构](fecshop-about-system-contruct.md)
    *  [Fecshop 安装-composer](fecshop-install.md)
    *  [Fecshop 安装-初始配置](fecshop-init-config.md)
    功能介绍
    --------
    *  [Fecshop 功能概叙](fecshop-feature-summary.md)
    *  [Fecshop Url自定义](fecshop-feature-url-custom.md)
    *  [Fecshop 多语言](fecshop-feature-mutil-languages.md)
    *  [Fecshop 多store](fecshop-feature-mutil-stores.md)
    *  [Fecshop 多货币](fecshop-feature-mutil-currency.md)
    *  [Fecshop 多模板](fecshop-feature-mutil-themes.md)
    *  [Fecshop 多入口](fecshop-feature-mutil-entrances.md)
    *  [Fecshop 配置层](fecshop-feature-config.md)
    *  [Fecshop 模块层](fecshop-feature-modules.md)
    *  [Fecshop Block层](fecshop-feature-block.md)
    *  [Fecshop 服务层](fecshop-feature-component-services.md)
    *  [Fecshop 独立功能块](fecshop-feature-independent-block.md)
    *  [Fecshop 权限管理](fecshop-feature-role.md)
    *  [Fecshop 缓存管理](fecshop-feature-cache.md)
    *  [Fecshop 脚本管理](fecshop-feature-script.md)
    *  [Fecshop 后台日志](fecshop-feature-admin-log.md)
    *  [Fecshop 重写功能](fecshop-feature-rewrite.md)
    *  [Fecshop 升级](fecshop-feature-upgrade.md)

在README.md文件里面你可以看到,在括号里面的文件 ,譬如 fecshop-jindu.md

你需要在 /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0下新建括号里面的md文件,然后在里面写内容就行了,譬如:

    关于 Fecshop 的框架特点
    =======================
    Fecshop 全称为Fancy ECommerce Shop,是一款优秀的开源电商系统,遵循[OSL3.0协议](http://www.oschina.net/question/28_8527),
    目的是为了方便yii2用户快速的
    开发商城,Fecshop作为一款可以持续性发展的商城系统,
    在框架层面有以下特性:
    1. 由于商城系统的复杂性,原始的框架MVC结构,显的有点力不从心,Fecshop框架
    加入了[Block层](fecshop-feature-block.md),
    Controller层只负责调度, Model只负责数据库映射,中间的处理逻辑由block来完成,View层
    负责显示,这样各司其职, 以免造成controller文件过于庞大。
    2. 加入[独立功能块](fecshop-feature-independent-block.md),有点类似Yii2的Widget,目的是为了让一些侧栏公用块
    可以通过配置的方式
    添加,同时,还可以具有设置缓存的功能,譬如侧栏的产品浏览记录,
    newsletter等独立显示块可能在很多
    页面用到,通过独立功能块可以配置方便的载入。
  1. 写个sh脚本用来生成文档,当然,您可以可以直接运行里面的代码,不过用sh运行比较方便:
rm -rf /www/web/online-2/www.fecshop.com/appfront/web/doc/fecshop-guide/cn-1.0/*
/www/web/develop/fecshopdoc/vendor/bin/apidoc  guide   /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0   /www/web/online-2/www.fecshop.com/appfront/web/doc/fecshop-guide/cn-1.0/  --interactive=0

md文件存放的地址为: /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0

md生成的html的地址为:/www/web/online-2/www.fecshop.com/appfront/web/doc/fecshop-guide/cn-1.0/

然后nginx 指向/www/web/online-2/www.fecshop.com/appfront/web

然后访问http://127.0.0.1/doc/fecshop-guide/cn-1.0/guide-index.html

就可以看到效果了

效果演示:http://www.fecshop.com/doc/fecshop-guide/cn-1.0/guide-index.html#

最后,您可能感觉样式不好,想改一下,可以修改;

vendor/bower/bootstrap/dist/css/bootstrap.css

或者添加文件,覆盖这个文件里面的css内容即可。

如果您要大改,把页面底部彻底换掉,可以到

/www/web/tadoc/vendor/yiisoft/yii2-apidoc/templates

这里找对应的代码,然后改掉html内容,在添加css内容等等

本文由 fecommerce 创作,采用 知识共享署名 3.0 中国大陆许可协议 进行许可。 可自由转载、引用,但需署名作者且注明文章出处。


微信

本帖已被设为精华帖!
共收到 2 条回复 yii2 apidoc
Luis#111个月前 0 个赞

实用的干货!

fecommerce#210个月前 1 个赞

最后,推荐一下我的Fecshop ,开源商城,github地址:https://github.com/fancyecommerce/yii2_fecshop

演示地址:http://fecshop.appfront.fancyecommerce.com/

截止到2016-11-12号,产品,分类,首页,评论,用户中心,搜索,多语言,多货币 等功能已经做完,除了购物车和支付部分,其他的基本都已经完成,关注fecshop的 在等2-3个月,也就是明年2,3月份,版本已经就可以出来,2017年4,5月份在把手机web 做一下,预计到明年5月份,后台,pc前台,手机web前台 ,命令控制台 这几个入口 基本可以完善,多谢大家关注和你们的Star,谢谢,我会坚持把他写好。

作者QQ:2358269014

添加回复 (需要登录)
需要 登录 后方可回复, 如果你还没有账号请点击这里 注册