Swagger v.s. apiDoc

Live Document

Swagger V.S. apidoc

http://swagger.io/

Swagger Core - Java-related libraries for generating and reading Swagger definitions

Swagger UI to generate interactive web-based documentation

Swagger Codegen - Command-line tool for generating both client and server side code from a Swagger definition

Swagger Editor - Browser based editor for authoring Swagger definitions in YAML or JSON format

https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X

apiDoc creates a documentation from API annotations in your source code.

評估考量

• 文件與程式邏輯同步性
• 統一格式 (易用性、可讀性)
• 學習成本 (門檻)
• 版本修改紀錄

Swagger

• Adding Swagger's dependencies to your project.
• Hook Swagger into your JAX-RS application configuration.
• Configure and Initialize Swagger.

優：

• 定義明確的 OpenAPI Specification
• 工具多 (基於 OpenAPI Specification)
• 網路資源多
• 同步性高

缺：

• 學習成本高，入門不易
• 必須是 Web Project
• Project 必須引入 Swagger Library

apiDoc

• Install

  npm install apidoc -g

• Use

  apidoc -i /example -o /apidoc

優：

• 類似 Javadoc 寫法
• no need to inject third party library
• have version change log
• easy to convert apidoc to swagger [https://github.com/fsbahman/apidoc-swagger]

缺：

• 註解行數多於程式碼
• 註解終歸是註解，還是有與程式邏輯不同步的可能性