Smart-doc は、Java RESTful API と Apache Dubbo RPC インターフェイスのドキュメント生成を同時にサポートするツールで、アノテーション侵入を使用してドキュメントを生成する swagger のような従来の実装方法を覆します。
Smart-doc は完全にインターフェースのソース コード分析に基づいてインターフェース ドキュメントを生成し、アノテーションの侵入を完全に実現します。必要なのは Java 標準のコメントに従って記述するだけで、シンプルで明確なマークダウンや GitBook のような静的ファイルの生成に役立ちます。スタイルの HTML ドキュメント。swagger などのドキュメント ツールの無数の注釈と強力な侵入汚染にうんざりしている場合は、smart-doc を採用してください。
特徴
- インターフェイスのデバッグをサポートします。
- アノテーションも学習コストもゼロで、標準の Java アノテーションを記述するだけで済みます。
- ソース コード インターフェイス定義に基づく自動導出、強力な戻り構造の導出。
- Spring MVC、Spring Boot、Spring Boot Web Flux (コントローラー書き込み)、JAX-RS 仕様をサポートします。
- Callable、Future、CompletableFuture、およびその他の非同期インターフェイスによって返される派生をサポートします。
- JavaBean での JSR303 パラメータ検証仕様をサポートし、グループ検証をサポートします。
- json リクエスト パラメーターのインターフェイスでは、モック json パラメーターを自動的に生成できます。
- 一般的に使用されるフィールド定義の中には、有効なアナログ値を生成できるものがあります。
- json 戻り値の例の生成のサポート。
- プロジェクト外部からのソースコードの読み込みをサポートし、フィールドアノテーションを生成します(標準仕様で公開されているjarパッケージを含む)。
- 複数の形式でのドキュメントの生成をサポート: Markdown、HTML5、Asciidoctor、Postman コレクション、Open API 3.0+。
- Spring Boot サービスで静的な HTML5 API ドキュメントをオンラインで簡単に表示できます。
- オープンな文書データ、文書管理システムへの自由なアクセス。
- コードコメント検出ツール、コメントを書かない友達の目から逃れることはできません。
- プラグインの高速統合 (Maven および Gradle プラグインをサポート)。
- Apache Dubbo RPC ドキュメント生成をサポートします。
- 国内のSolonアプリケーション開発フレームワークをサポートします。
Smart-doc 公式サイトアドレス:ドキュメント
1 プロジェクト内に /src/main/resources/smart-doc.json 構成ファイルを作成します。
2 設定内容は以下の通りです(ドキュメントの出力パスを指定)
{
"outPath": "D://md2"
}
3 pom.xml の下に設定を追加します
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.1.0</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>测试</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码,如果一些框架依赖库
加载不到导致报错,这时请使用excludes排除掉-->
<excludes>
<!--格式为:groupId:artifactId;参考如下-->
<!--也可以支持正则式如:com.alibaba:.* -->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
<!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部
源代码而不是自动加载所有,因此使用时需要注意-->
<!--smart-doc能自动分析依赖树加载所有依赖源码,原则上会影响文档构建效
率,因此你可以使用includes来让插件加载你配置的组件-->
<includes>
<!--格式为:groupId:artifactId;参考如下-->
<!--也可以支持正则式如:com.alibaba:.* -->
<include>com.alibaba:fastjson</include>
<!-- 如果配置了includes的情况下, 使用了mybatis-plus的分页需要
include所使用的源码包 -->
<include>com.baomidou:mybatis-plus-extension</include>
<!-- 如果配置了includes的情况下, 使用了jpa的分页需要include所使用
的源码包 -->
<include>org.springframework.data:spring-data-commons</include>
</includes>
</configuration>
<executions>
<execution>
<!--如果不需要在执行编译时启动smart-doc,则将phase注释掉-->
<phase>compile</phase>
<goals>
<!--smart-doc提供了html、openapi、markdown等goal,可按需配置-->
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
4 プラグインを実行する
5 ストレージパスを見つけてブラウザを開きます
6 テスト結果