Doxygen程式碼文件產生器

有個需求，需要提供API文件給其他團隊。評估線上與離線方案：

線上式：

Postman：適合團隊協同合作。但團隊外不是很合適。
Swagger：需額外在專案裡開Endpoint與還會造成額外的（安全）維護成本。

離線式：

DocFX
Sandcastle

都有在考慮範圍，但試過之後效果不理想。

doxygen

後來發現一套doxygen，除了GUI使用方便之外，另外還能透過指令（doxygen.exe）很方便整合進CI/CD的環境。

以下用我常用的 Northwind - ProductsController 為例來設定 doxygen，並透過 GUI 與 doxygen.exe 來產生API文件（前提是好好寫註解）。

注意一下，<example><code>~~~</code></example>這樣的階層才能產生正確效果。也就是，以下範例除了POST，其他的<example/>不會有效果。
其他XML註解的效果，可能還要多測試。

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using northwindSample.Models;

namespace northwindSample.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class ProductsController : ControllerBase
    {
        private readonly NorthwindContext _context;

        public ProductsController(NorthwindContext context)
        {
            _context = context;
        }

        /// <summary>
        /// 取得所有產品資料
        /// </summary>
        /// <returns>所有產品清單</returns>
        /// <example>
        /// GET /api/Products
        /// </example>
        [HttpGet]
        public async Task<ActionResult<IEnumerable<Product>>> GetProducts()
        {
            if (_context.Products == null)
            {
                return NotFound();
            }
            return await _context.Products.ToListAsync();
        }

        /// <summary>
        /// 取得某一筆產品資料
        /// </summary>
        /// <param name="id">產品編號</param>
        /// <returns>單一產品資料</returns>
        /// <example>
        /// GET /api/products/{id}
        /// </example>
        [HttpGet("{id}")]
        public async Task<ActionResult<Product>> GetProduct(int id)
        {
            if (_context.Products == null)
            {
                return NotFound();
            }
            var product = await _context.Products.FindAsync(id);

            if (product == null)
            {
                return NotFound();
            }

            return product;
        }

        /// <summary>
        /// 更新指定的產品資料
        /// </summary>
        /// <param name="id">產品編號</param>
        /// <param name="product">Product物件</param>
        /// <returns>HTTP狀態碼</returns>
        /// <remarks>
        /// To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        /// </remarks>
        /// <example>
        /// PUT /api/products/{id}
        ///
        /// {
        ///     Product Object
        /// }
        /// </example>
        [HttpPut("{id}")]
        public async Task<IActionResult> PutProduct(int id, Product product)
        {
            if (id != product.ProductId)
            {
                return BadRequest();
            }

            _context.Entry(product).State = EntityState.Modified;

            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException)
            {
                if (!ProductExists(id))
                {
                    return NotFound();
                }
                else
                {
                    throw;
                }
            }

            return NoContent();
        }

        /// <summary>
        /// 新增一筆產品資料
        /// </summary>
        /// <param name="product">Product物件</param>
        /// <returns>HTTP狀態碼</returns>
        /// <remarks>
        /// To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        /// <example>
        /// <code>
        /// POST /api/products
        ///
        /// {
        ///     Product Object
        /// }
        /// </code>
        /// </example>
        /// </remarks>
        /// <example>
        /// <code>
        /// POST /api/products
        ///
        /// {
        ///     Product Object
        /// }
        /// </code>
        /// </example>
        [HttpPost]
        public async Task<ActionResult<Product>> PostProduct(Product product)
        {
            if (_context.Products == null)
            {
                return Problem("Entity set 'NorthwindContext.Products'  is null.");
            }
            _context.Products.Add(product);
            await _context.SaveChangesAsync();

            return CreatedAtAction("GetProduct", new { id = product.ProductId }, product);
        }

        /// <summary>
        /// 刪除指定的產品資料
        /// </summary>
        /// <param name="id">產品編號</param>
        /// <returns>HTTP狀態碼</returns>
        /// <example>
        /// DELETE /api/products/{id}
        /// </example>
        [HttpDelete("{id}")]
        public async Task<IActionResult> DeleteProduct(int id)
        {
            if (_context.Products == null)
            {
                return NotFound();
            }
            var product = await _context.Products.FindAsync(id);
            if (product == null)
            {
                return NotFound();
            }

            _context.Products.Remove(product);
            await _context.SaveChangesAsync();

            return NoContent();
        }

        private bool ProductExists(int id)
        {
            return (_context.Products?.Any(e => e.ProductId == id)).GetValueOrDefault();
        }
    }
}

開啟Doxygen GUI，這個Doxygen GUI是幫你產生doxyfile組態檔，底層也是透過doxygen.exe來執行。

Wizard 頁籤

Project是填入最重要的幾項資料：

working directory：類似暫存目錄
Project name：專案名稱
Project version: 文件版本
Source Code: 原始碼目錄。
- San recursively：如果沒勾選，只會Scan當下目錄裡的.cs檔案。
Destination directory: 文件輸出目錄

選擇模式

extraction mode: Documented entities only(預設) / All Entities
- 測試專案太小，試不太出來兩者的差異。
Select programming language: Optimize for Java or C# output

輸出。我們只需要HTML，因此只保留HTML選項。

類別圖。保留預設值。

Expert

OUTPUT_LANGUAGE 可調整輸出UI的語系。
FULL_PATH_NAME 是否輸出檔案路徑。(可取消勾選，以免曝過過多資訊)

Run

點擊Run doxygen之後，點擊Show HTML output，查看產出文件的效果。

組態檔

Doxygen GUI產生沒問題之後，就可以一直寫註解及測試效果。完成之後，可以把組態保留。

File --> Save as ... --> Doxyfile

下次開啟Doxygen GUI就能匯入Doxyfile來使用。

doxygen.exe

C:\Program Files\doxygen\bin

當我們有了組態檔之後，就能拿來透過指令碼方式來產生文件：

PS C:\> doxygen.exe .\Doxyfile

都沒問題之後，就能把 Doxyfile 加入版控，讓後續的CI/CD去做自動化產生文件的工作。

結論

doxygen幾個優點：

設定簡單，入手容易。
非依賴DLL，直接掃.cs檔案，文件產生快速。
支援指令碼模式，讓CI/CD自動化產生與更新文件可行。

KingKong Bruce記事

網頁