IOS技术分享｜iOS快速生成开发文档（一）

言

对于开发人员而言，文档的作用不言而喻。文档不仅可以提高软件开发效率，还能便于以后的软件开发、使用和维护。本文主要讲述 Objective-C 快速生成开发文档工具 appledoc。

简介

appledoc 是一个命令行工具，它可以帮助 Objective-C 开发者从特殊格式的源代码注释中生成类似 Apple 的源代码文档。它的设计目的是在输入时尽可能采 HTML 格式文档，以及完全索引和可浏览的 Xcode 文档集。

支持的注释

`/// 这是单行注释。`

`/** 这也是单行注释 */`

`/*! 同样是单行注释 */`

`/** 这也是单行注释，`

`*  第二行会接上第一行。`

`*/`

`/** 第一行是类的简介`

`在简介的下面,就是类的详细介绍了。`

`没有间隔换行会被消除，就像Html那样。`

`下面是常用的markdown语法`

`- - -`

`无序列表: (每行以 '*'、'-'、'+' 开头):`

`* this is the first line`

`* this is the second line`

`* this is the third line`

`有序列表: (每行以 1.2.3、a.b.c 开头):`

`a. this is the first line`

`b. this is the secode line`

`多级列表:`

`* this is the first line`

`a. this is line a`

`b. this is line b`

`* this is the second line`

`1. this in line 1`

`2. this is line 2`

`标题:`

`# This is an H1`

`## This is an H2`

`### This is an H3`

`#### This is an h4`

`##### This is an h5`

`###### This is an H6`

`链接:`

`普通URL直接写上，appledoc会自动翻译成链接: [http://    blog.ibireme.com](http://    blog.ibireme.com)`

`[这个]([http://example.net/](http://example.net/)) 链接会隐藏实际URL.`

`表格:`

`| header1 | header2 | header3 |`

`|---------|:-------:|--------:|`

`| normal  |  center |  right  |`

`| cell    | cell    | cell    |`

`引用:`

`这里会引用到方法 `someMethod:`，这里会引用到类 `YYColor``

`这里会引用到一个代码块`

`void CMYK2RGB(float c, float m, float y, float k, `

`float *r, float *g, float *b) {`

`*r = (1 - c) * (1 - k);`

`*g = (1 - m) * (1 - k);`

`*b = (1 - y) * (1 - k);`

`}`

`@since iOS5.0`

`*/`

`@interface AppledocExample : NSObject`

`///这里是属性的说明`

`@property (nonatomic, strong) NSString *name;`

`/** `

`@brief 这里是方法的简介。该Tag不能放到类注释里。`

`@exception UIColorException 这里是方法抛出异常的说明`

`@see YYColor`

`@see someMethod:`

`@warning 这里是警告，会显示成蓝色的框框`

`@bug 这里是bug，会显示成黄色的框框`

`@param red   这里是参数说明1`

`@param green 这里是参数说明2`

`@param blue   这里是参数说明3`

`@return  这里是返回值说明`

`*/`

`- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;`

`- (void)someMethod:(NSString *)str;`

`@end`

安装 appledoc 环境

方式一：

打开终端，输入以下命令：

// 下载代码
git clone git://github.com/tomaz/appledoc.git

// 进入目录
cd ./appledoc

//执行安装脚本
sudo sh install-appledoc.sh

// 检验是否安装成功
appledoc --version

安装第3步报错

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

解决：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer/

方式二：

前提安装了 Homebrew（在此不作赘述）

brew install appledoc

生成文档

创建一个 app 工程，拖入.h文件

TARGETS -> Build Phases -> Run Script 中添加脚本

/usr/local/bin/appledoc \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/${company}" \
--output "${outputPath}" \
--publish-docset \
--docset-platform-family "${target}" \
--logformat xcode \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--exit-threshold 2 \
"${PROJECT_DIR}/${docFilePath}"

指令用法

# 参考指令写法1(不生成docset文件)
$ appledoc --no-create-docset --output ./doc --project-name "工程名" --company-id "bundle id" --project-company "公司名" ./
# 参考指令写法2(不生成docset文件，参数使用“=”等号写法)
$ appledoc --no-create-docset --output="./doc" --project-name="工程名" --company-id="bundle id" --project-company="公司名" ./
# 参考指令写法3(生成docset文件并指定生成路径)
$ appledoc --output ./doc --project-name "工程名" --company-id "bundle id" --project-company "公司名" ./ --docset-install-path ./doc
# 以上都是扫描指定目录下的文件，如果想扫描当前目录所有文件，只需要将指定目录换成"."即可
$ appledoc --no-create-docset --output="./doc" --project-name="工程名" --company-id="bundle id" --project-company="公司名" .

例如：终端进入 app 目录，执行

$ appledoc --project-name ARtcKit_4.2.2.7 --project-company anyrtc ./

文档效果

者：前端小智来源：大迁世界

.md文件是markdown的一种标记语言，和html比较起来，更简单快捷，主要体现在：标记符的数量和书写上。

标记符的数量：html文档需要用到数量繁多的标记符，再辅以css来控制样式和排版，而markdown文档只需要四个基本的标记符号就能完成同样的事。
标记符的书写：HTML文档内容需要同时标记开始和结束这是一个网页，而markdown文档则只要在开始位置标记即可# 这是一个md文档。下面介绍如何实现将.md文件转换成.html文件。

方式一：使用i5ting_toc插件

需要先安装npm(安装node.js后会自带npm)，然后才能安装i5ting插件：

npm install i5ting_toc -g

执行命令行生成html文件，在输入前要进入到对应根目录下：

i5ting_toc -f **.md

需要注意的是：写md文档的特殊符号时记得添加空格。小技巧：如何快速在当前目录打开cmd?选择当前目录，按住shift，然后鼠标右键在此处打开命令窗口(在此处打开powerShell窗口)。

方式二：使用gitbook

同样先需要安装node，然后运行：

npm i gitbook gitbook-cli -g

生成md文件,这个命令会生成相应的md的文件，然后在相应的文件里写你的内容即可：

gitbook init

md转html,生成一个_doc目录，打开就可以看到你html文件了。

gitbook build

方式三：利用前端代码

实现原理是采用node.js搭建服务器，读取md文件转化为html片断。浏览器发送ajax请求获取片段后再渲染生成html网页。

node代码：

var express = require('express');
var http = require('http');
var fs = require('fs');
var bodyParser = require('body-parser');
var marked = require('marked'); // 将md转化为html的js包
var app = express();

app.use(express.static('src')); //加载静态文件
var urlencodedParser = bodyParser.urlencoded({ extended: false });

app.get('/getMdFile',urlencodedParser, function(req, res) {
var data = fs.readFileSync('src/test.md', 'utf-8'); //读取本地的md文件
res.end(JSON.stringify({
body : marked(data)
}));
} );

//启动端口监听
var server = app.listen(8088, function () {
var host = server.address().address;
var port = server.address().port;
console.log("应用实例，访问地址为 http://%s:%s", host, port)
});

前端html：

<div id="content"> <h1 class="title">md-to-HTML web app</h1> <div id="article"> </div></div><script type="text/JavaScript" src="js/jquery-1.11.3.min.js"></script><script> var article = document.getElementById('article'); $.ajax({ url: "/getMdFile", success: function(result) { console.log('数据获取成功'); article.innerHTML = JSON.parse(result).body; }, error: function (err) { console.log(err); article.innerHTML = '<p>获取数据失败</p>'; } });</script>

. smart-doc简介

smart-doc是一款接口文档生成工具，它完全是根据接口源码进行分析生成接口文档，不会使用任何注解侵入业务代码中。这一点与swagger完全不同，swagger侵入性强，需要编写大量注解。

在Java项目中，我们只需要按照java-doc的标准编写注释，就能生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+格式的文档。

smart-doc帮助文档：https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc

二. SpringBoot项目集成smart-doc

1. 完善项目中的注释

给实体类添加相关的注释，如下图所示：

我们在控制器上也添加应有的注释

注意：我们项目中的类、方法、属性，都必须使用文档注释！

作为开发人员，一定要养成规范编写注释的好习惯。

2. smart-doc的配置信息

接着我们要在resource目录下新建一个smart-doc.json文件，在该文件中输入如下内容：

smart-doc的配置项很多，其他各种配置可参考上文提到的帮助文档进行查看。

3. 配置smart-doc插件

接着我们要在pom.xml文件的plugins标签中，增加如下内容：

<configFile>中指定需要调用的smart-doc配置文件的路径。

4. 生成文档

在idea中，我们可以直接通过插件生成smart各种格式的文档，如下图所示：

在本例中，我们双击smart-doc:html就可以生成html格式的接口文档。

生成文档后，所在目录中的内容如下：

配置"allInOne": true后，生成的文档中只会包含一个index.html文件。如果设置为false，生成的接口文档会包括api.html、dict.html和error.html多个文件，大家可以自行测试。

5. 接口文档界面效果

最后我们双击index.html，就可以查看生成的接口文档效果了。

大家可以根据上文的smart-doc配置，找找每个配置在接口文档中对应显示的内容。

三. 接口测试

1. 配置调试页面进行测试

1.1 生成文档

根据上文的配置，默认情况下，仅是生成接口文档，配置"createDebugPage": true，双击插件的smart-doc:html选项，即可生成带接口调用功能的接口文档。怎么样，这个功能是不是相当强大？

生成带调试功能的接口文件，如下所示：

1.2 运行测试

此时双击debug-all.html，运行测试文档后，页面如下：

2. 导入ApiPost进行测试

2.1 生成postman格式文档

接着我们再双击smart-doc:postman，生成一个postman格式的文档：

生成的postman格式文档如下所示：

2.2 导入文档

我们还可以在ApiPost中导入该文档，其步骤如下：

2.3 测试接口

导入后，我们可以切换到导入的项目，这样就可以进行接口测试了。

在线咨询

上一篇：HTML5来了：5个好用的混合式App开发工具
下一篇：技术贴：一篇文章看懂链接（超链接）设计

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

整合营销服务商