Swaggerに新しいスキンを与えると、たちまち背筋が伸びる！

概要

APIドキュメント生成ツールとしてのSwaggerは、機能は非常に完璧ですが、まだいくつかの欠点があります。これらの欠点を補うためにKnife4jを偶然発見し、Swaggerに多くの機能を与えました。

knife4j

knife4jは、Swaggerの使用におけるJava開発者のためのspringfox-swagger強化UI実装であり、簡潔で強力なインターフェイスのドキュメンテーションの経験を提供します。Swagger、あなたはシームレスにknife4jに切り替えることができます。

クイックスタート

次は、SpringBootでknife4jを使う方法を2ステップで紹介します！

• pom.xmlにknife4j関連の依存関係を追加します；

<!--統合Knife4j>
<dependency>
 <groupId>com.github.xiaoymin</groupId>
 <artifactId>knife4j-spring-boot-starter</artifactId>
 <version>2.0.4</version>
</dependency>

• Swagger2Configに@EnableKnife4jアノテーションを追加し、knife4jの機能拡張を有効にします；

/**
 * Swagger2APIドキュメントの構成
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
 
}

• SpringBootアプリケーションを実行し、APIドキュメンテーションのアドレスを参照してください：

特徴

次にSwaggerと比較し、knife4jの使い方がどう違うかを確認します！

JSON機能強化

通常、Swaggerを使用してきましたが、SwaggerのJSONサポートはあまり良くありませんでした、JSONは折りたたむことができない、見るには長すぎる、JSON形式のパラメータを渡す、パラメータチェックサム機能がありません。knife4jのこれらのペインポイントは解決されています。

• 返される結果セットは、見やすく折りたたむことができます；

• リクエストパラメータにはJSONチェックサムがあります。

ログイン

Knife4jはまた、ログイン認証使用のためにヘッダーにTokenを追加することをサポートしています。

• まず、Authorize関数にログインから返されたTokenを追加します；

• その後、それぞれのインターフェイスで、Token情報がリクエストヘッダに含まれていることがわかります。

オフライン・ドキュメント

オフラインドキュメントをエクスポートするためのKnife4jサポート , 他の人に送信するのは簡単 , サポートMarkdown形式 .

• 直接ドキュメント管理 -> オフラインドキュメント機能を選択し、Markdownのダウンロードを選択します；

• エクスポートされたMarkdownのオフライン・ドキュメントをご覧ください。

グローバルパラメーター

グローバルパラメータの一時的な設定のためのKnife4jのサポート、クエリ（フォーム）の2つのタイプのサポート、ヘッダ（リクエストヘッダ） 。

• 例えば、アンドロイドかiosかを区別するために、すべてのリクエストヘッダにappTypeパラメータを追加したい場合、グローバルパラメータに追加することができます；

• この時点で、インターフェイスが再度呼び出されると、リクエストヘッダー appTypeが含まれます。

パラメータ属性の無視

作成と変更のインターフェイスがリクエストパラメータとして同じオブジェクトを使うことがありますが、作成時にはidは必要ありません。

• @ApiOperationSupport例えば、ここでのcreate productインターフェイスでは、id、商品数、商品コメント数は、バックエンドインターフェイスによって、それらを渡すことなく生成することができ、Knife4jによって提供されるアノテーションを使用することで、それらを無視することができます；

/**
 * ブランドマネジメントコントローラー
 * Created by macro on 2019/4/19.
 */
@Api(tags = "PmsBrandController", description = "マーチャンダイズ・ブランド・マネジメント")
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
 @Autowired
 private PmsBrandService brandService;
 private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
 @ApiOperation("ブランディングの追加")
 @ApiOperationSupport(ignoreParameters = {"id","productCount","productCommentCount"})
 @RequestMapping(value = "/create", method = RequestMethod.POST)
 @ResponseBody
 public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
 CommonResult commonResult;
 int count = brandService.createBrand(pmsBrand);
 if (count == 1) {
 commonResult = CommonResult.success(pmsBrand);
 LOGGER.debug("createBrand success:{}", pmsBrand);
 } else {
 commonResult = CommonResult.failed("操作失敗");
 LOGGER.debug("createBrand failed:{}", pmsBrand);
 }
 return commonResult;
 }
}

• インターフェイスのドキュメントを表示するには、この時点で、3つの属性が消えていることがわかったので、フロントエンドの開発は、インターフェイスのドキュメントを表示するには、無駄なパラメータを定義することを感じることはありません、非常に良い機能ではありません！

公式ドキュメント：

、学習チュートリアルのシリアルのフルセットは、最初のアクセスを公開に従ってください。