Live Document
Swagger V.S. apidoc
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
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]
缺:
- 註解行數多於程式碼
- 註解終歸是註解,還是有與程式邏輯不同步的可能性
沒有留言:
張貼留言