初心者に最適なSpringBoot+SSMプロジェクト「Sky Takeaway」実戦 - (4) Swaggerの統合

記事ディレクトリ

Dark Horse Programmer の最新 Java プロジェクト実戦「Sky Takeaway」、初心者向けに最適な SpringBoot+SSM エンタープライズレベル Java プロジェクト実戦。

Swagger の概要

Swagger は、RESTful API の記述、設計、開発、テストに使用できるオープンソースの API 設計ツールです。RESTful API を記述および提示するための標準化された方法を提供し、API ドキュメントに従ってクライアントおよびサーバーのコードを生成できるため、API の開発と展開が迅速化されます。Swagger を使用すると、開発者はシンプルで強力な API 対話を使用して、RESTful アプリケーションを迅速に構築、テスト、デプロイできます。

Spring は Swagger を独自の標準に組み込み、現在 Springfox と呼ばれる Spring-swagger プロジェクトを確立しました。Springfox をプロジェクトに導入すると、Swagger を非常に簡単かつ迅速に使用できるようになります。

YApi とは異なり、Yapi はインターフェイスを管理および保守するために設計段階で使用されるツールであり、Swagger はバックエンド開発者がバックエンドインターフェイスのテストを行うのを支援するために開発段階で使用されるフレームワークです。

Knife4j は Swagger フロントエンド UI 拡張ライブラリであり、Swagger に基づいて API ドキュメントを生成し、より強力な UI インターフェイスと対話型エクスペリエンスを提供します。Knife4j は、インターフェイスのテスト、インターフェイスのオンラインデバッグ、インターフェイスドキュメントのエクスポートなど、API 開発の効率と信頼性を大幅に向上させる豊富な機能を提供します。Knife4j は SpringBoot と SpringMvc に基づいて開発されており、複数のドキュメント形式のエクスポートをサポートし、カスタム UI スタイルとテーマもサポートしています。Knife4j はオープンソースであり、自由に使用および変更できます。

Swagger の統合

pom.xml に Knife4j 依存関係を追加します。

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

WebMvcConfiguration.java 構成クラスに Knife4j 関連の構成を追加します。

/**
* 通过knife4j生成接口文档
* @return
*/
@Bean
public Docket docket() {
      
      
  ApiInfo apiInfo = new ApiInfoBuilder()
    .title("苍穹外卖项目接口文档")
    .version("2.0")
    .description("苍穹外卖项目接口文档")
    .build();
  Docket docket = new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo)
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
    .paths(PathSelectors.any())
    .build();
  return docket;
}

WebMvcConfiguration.java で静的リソースマッピングを設定します。そうしないと、インターフェイスのドキュメントページにアクセスできません。

/**
* 设置静态资源映射
* @param registry
*/
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
      
      
  registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
  registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

ブラウザでインターフェイスドキュメントパスhttp://localhost:8080/doc.htmlにアクセスします。
インターフェイステスト、ログインインターフェイスのテスト [ログイン]:

共通の注意事項

生成されたインターフェイスドキュメントは、Swagger が提供するアノテーションを通じて制御して、インターフェイスドキュメントを読みやすくすることができます。一般的に使用されるアノテーションは次のとおりです。

注釈	説明する
@アピ	クラスの説明を示すために、コントローラーなどのクラスで使用されます。
@ApiModel	エンティティ、DTO、VO などのクラスで使用されます。
@ApiModelProperty	属性情報を記述するために属性で使用されます
@ApiOperation	メソッドの目的と機能を説明するために、Controller のメソッドなどのメソッドで使用されます。

次に、上記の注釈を使用して、より読みやすいインターフェイスのドキュメントを生成します。

sky-server モジュールの EmployeeController.java クラスを変更し、クラスのメソッドを追加し@Apiてコメントします@ApiOperation。

@Api(tags = "员工相关接口")
public class EmployeeController {
      
      

    @PostMapping("/login")
    @ApiOperation(value = "员工登录")
    public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) 	{
      
      
        //..............
    }

    @PostMapping("/logout")
    @ApiOperation("员工退出")
    public Result<String> logout() {
      
      
        return Result.success();
    }

}

サービスを開始します: http://localhost:8080/doc.html にアクセスします。