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小時內與您取得聯系。

整合營銷服務商