Swaggerを新しいスキンに変更すると、すぐに背が高くなりました

著者：macrozheng

元のリンク：https://mp.weixin.qq.com/s/XbBD0E136F72gI6OkVIZeA

Swagger、APIドキュメント生成ツールとして、機能は非常に完全ですが、まだいくつかの欠点があります。偶然、knife4jがこれらの欠点を補い、Swaggerにさらに多くの機能を提供していることがわかりましたが、今日はその使用方法について説明します。

knife4jの紹介

Knife4jは、Springfox-swaggerの拡張されたUI実装であり、Swaggerを使用するときにJava開発者にシンプルで強力なインターフェースドキュメントエクスペリエンスを提供します。Knife4jは完全にspringfox-swaggerの使用方法に準拠しており、それに基づいて機能が強化されています。

クイックスタート

次に、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>

• @ EnableKnife4jアノテーションをSwagger2Configに追加すると、knife4jの拡張機能を有効にできます。

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
    }

• SpringBootアプリケーションを実行し、APIドキュメントのアドレスにアクセスして表示します。http：// localhost：8088 / doc.html

 

特徴

次に、Swaggerを比較して、knife4jとそれの違いを見てみましょう！

JSON関数の機能強化

私はいつもSwaggerを使用していますが、SwaggerのJSONサポートはあまり良くありません。JSONは折りたたむことができず、長すぎて表示できません。JSON形式のパラメーターを渡す場合、パラメーター検証関数はありません。これらの問題点は、knife4jで解決されました。

• 返された結果セットは、見やすいように折りたたみをサポートしています。

 

• リクエストパラメーターにはJSON検証機能があります。

 

ログイン認証

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

• 最初に、ログインによって返されたトークンをAuthorize関数に追加します。

 

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

 

オフラインドキュメント

knife4jは、他の人に簡単に送信できるようにオフラインドキュメントのエクスポートをサポートし、Markdown形式をサポートしています。

• 文書管理->オフライン文書機能を直接選択し、Markdownのダウンロードを選択します。

 

• エクスポートされたMarkdownオフラインドキュメントを確認してみましょう。これはまだ非常に詳細です。

 

グローバルパラメータ

knife4jは、グローバルパラメータの一時的な設定をサポートし、2種類のクエリ（フォーム）とヘッダー（リクエストヘッダー）をサポートしています。

• たとえば、すべてのリクエストヘッダーにパラメーターappTypeを追加して、それがandroid呼び出しかios呼び出しかを区別したい場合は、グローバルパラメーターに追加できます。

 

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

 

パラメータ属性を無視する

作成して変更するインターフェイスがリクエストパラメータと同じオブジェクトを使用する場合がありますが、作成時にIDは必要なく、変更時にIDが必要になります。現時点では、ID属性を無視できます。

• たとえば、ここの製品作成インターフェースでは、バックグラウンドインターフェースを渡さなくても、ID、製品数量、製品コメント番号を生成できます。knife4jが提供する@ApiOperationSupportアノテーションを使用すると、これらの属性を無視できます。

/**
 * 品牌管理Controller
 * 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つの属性が消えているため、フロントエンド開発では、インターフェースドキュメントを表示するときに不要なパラメーターを定義したように感じることはありません。

 

参照

公式ドキュメント：https://doc.xiaominfo.com/guide/

プロジェクトのソースアドレス

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-knife4j