SpringBoot は Swagger をどのように統合しますか?

Spring Boot は、Spring フレームワークをベースにした軽量のオープンソース フレームワークであり、その登場により、Spring アプリケーションの構築と開発が大幅に簡素化されます。開発プロセスにおいて、インターフェイスのドキュメントは非常に重要な部分であり、開発者がインターフェイスの機能とパラメータを確認して理解するのを容易にするだけでなく、フロントエンド開発とバックエンド開発が連携して開発効率を向上させるのにも役立ちます。

1. Swagger について

Swagger は、RESTful インターフェイス ドキュメントの仕様およびツールセットであり、その目標は、RESTful インターフェイス ドキュメントの形式と仕様を統一することです。開発プロセスにおいて、インターフェイスのドキュメントは非常に重要な部分であり、開発者がインターフェイスの機能とパラメータを確認して理解するのを容易にするだけでなく、フロントエンド開発とバックエンド開発が連携して開発効率を向上させるのにも役立ちます。 Spring Boot では Swagger を統合して、インターフェイス ドキュメントを自動的に生成できます。注釈を使用してインターフェイスを記述することにより、Swagger はインターフェイス ドキュメントを自動的に生成できます。

2. Swagger のインストール

1. Swagger のダウンロード

Swagger の公式 Web サイトは https://swagger.io/ で、ここから Swagger の最新バージョンをダウンロードできます。 。

2. Swagger のインストール

ダウンロードした Swagger を指定したディレクトリに解凍するだけで、このインストール プロセスは非常に簡単です。解凍したディレクトリには、Swagger の UI インターフェイスである swagger-ui.html ページがあります。

3. Swagger の使用

1. インターフェイスの作成

インターフェイスを作成するときは、Swagger アノテーションを使用してインターフェイス情報を記述する必要があります。一般的に使用されるアノテーションは次のとおりです。

• @Api: インターフェイスの説明に使用されるクラスまたはインターフェイス

• @ApiOperation: インターフェイスの説明に使用されるメソッド

• #@ApiParam: インターフェイスのパラメータの記述に使用

##@ApiModel: データ モデルの記述に使用

• ##@ApiModelProperty: データ モデルを記述するために使用されるプロパティ

• たとえば、単純なインターフェイスを作成します:

@RestController
@Api(tags = "用户接口")
public class UserController {
 
    @GetMapping("/user/{id}")
    @ApiOperation(value = "根据 ID 获取用户信息")
    public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) {
        // 根据 ID 查询用户信息
    }
}

上記のコードでは、@Apiクラスがユーザーインターフェースであること、@ApiOperationがメソッドがユーザー情報を取得するインターフェースであること、@ApiParamがパラメーターがユーザーIDであること、@PathVariableがパスパラメーターであることを示します。

2. Swagger を有効にする

Spring Boot では、Swagger 関連の依存関係を追加することで Swagger を有効にできます。

pom.xml ファイルに次の依存関係を追加できます:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Spring Boot では、Swagger を構成するための構成クラスも追加する必要があります。構成クラスのコードは次のとおりです。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
}

上記のコードでは、@Configuration はクラスが構成クラスであることを示し、@EnableSwagger2 は Swagger が有効であることを示します。 api() メソッドでは、`select() メソッドを通じてスキャンされたパッケージのパスを設定し、paths() メソッドを通じてインターフェイスのアクセス パスを設定し、apiInfo() メソッドを通じてインターフェイス ドキュメントの関連情報を設定します。

3. インターフェイス ドキュメントの表示

Spring Boot アプリケーションを開始した後、ブラウザーで http://localhost:8080/swagger-ui.html にアクセスしてインターフェイス ドキュメントを表示できます。 Swagger UI ページでは、インターフェイス名、リクエスト メソッド、リクエスト パス、リクエスト パラメーター、応答パラメーターなどを含むすべてのインターフェイス情報を確認できます。

4. Swagger の高度な使用法

1. データ モデルの説明

@ApiModel

と

@ApiModelProperty を使用できますデータモデルとプロパティを説明するための注釈。たとえば、User クラスを作成し、そのクラスで @ApiModel と

@ApiModelProperty 注解来描述该数据模型：

@ApiModel(description = "用户信息")
public class User {
 
    @ApiModelProperty(value = "用户 ID", example ="1") 
    private Long id;

	@ApiModelProperty(value = "用户名", example = "张三")
	private String username;

	@ApiModelProperty(value = "密码", example = "123456")
	private String password;

	// 省略 getter 和 setter 方法
}

を使用できます。上記のコードでは、@ApiModel はクラスがデータ モデルであることを示し、@ApiModelProperty はプロパティがデータ モデル.属性、value 属性は属性の説明を表し、example 属性は属性の値の例を表します。

2. 列挙型の記述

@ApiModel

および

@ApiModelProperty アノテーションを使用して列挙型を記述できます。たとえば、Gender 列挙型を記述し、その列挙値に @ApiModelProperty アノテーションを使用して列挙値を記述することができます。

@ApiModel(description = "性别") public enum Gender {

@ApiModelProperty(value = "男")
MALE,

@ApiModelProperty(value = "女")
FEMALE;
}

上記のコードでは、@ApiModel は列挙型が An 列挙型であることを示しています。 @ApiModelProperty は、列挙値が男性を表す列挙値であるか、女性を表す列挙値であることを示します。

3. 応答パラメーターの説明

@ApiResponses および @ApiResponse アノテーションを使用して API 応答パラメーターを定義できます。たとえば、getUserById() メソッドを記述し、そのメソッドで @ApiResponses および @ApiResponse アノテーションを使用して、メソッドの応答パラメーターを記述することができます。

@GetMapping("/user/{id}")
@ApiOperation(value = "根据 ID 获取用户信息") 
@ApiResponses({ @ApiResponse(code = 200, message = "请求成功", response = User.class), 
@ApiResponse(code = 404, message = "用户不存在") }) 
public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) 
{ 
	// 根据 ID 查询用户信息 
}

上記のコードでは、@ApiResponses は、メソッド パラメーターでは、@ApiResponse は応答パラメーターの説明を表し、code 属性は応答コードを表し、message 属性は応答メッセージを表し、response 属性は応答データ モデルを表します。

5. Swagger の高度な使用法

1. グローバル パラメーターの構成

メソッド globalOperationParameters() を使用すると、構成クラスでグローバル パラメーターを構成できます。グローバル認証パラメータを設定することで認証できます

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(Arrays.asList(
                        new ParameterBuilder()
                                .name("Authorization")
                                .description("授权")
                                .modelRef(new ModelRef("string"))
                                .parameterType("header")
                                .required(false)
                                .build()
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

上記のコードでは、globalOperationParameters() メソッドを介して認証用のグローバル認証パラメータを設定します。

2、配置安全协议

通过在配置类中调用 securitySchemes() 方法，我们能够进行安全协议的配置。举个例子，可以设置 Bearer Token 作为安全协议

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Arrays.asList(
                        new ApiKey("Bearer", "Authorization", "header")
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

在上面的代码中，我们通过 securitySchemes() 方法来配置一个 Bearer Token 安全协议。

3、配置安全上下文

使用 securityContexts() 方法配置安全上下文是配置类中的一种可选方法。举个例子，我们可以设置一个安全上下文来在Swagger UI中展示认证按钮：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Arrays.asList(
                        new ApiKey("Bearer", "Authorization", "header")
                ))
                .securityContexts(Collections.singletonList(
                        SecurityContext.builder()
                                .securityReferences(Collections.singletonList(
                                        new SecurityReference("Bearer", new AuthorizationScope[0])
                                ))
                                .build()
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

在上面的代码中，我们通过 securityContexts() 方法来配置一个安全上下文，用于在 Swagger UI 中显示认证按钮。

4、配置忽略参数

在API文档中，可能有些参数包含敏感信息，因此需要保护这些信息不被公示。我们可以使用 @ApiIgnore 注解来忽略这些参数。在 User 类中，我们可以使用 @ApiIgnore 注解来排除密码参数

@ApiModel(description = "用户信息")
public class User {
 
    @ApiModelProperty(value = "用户 ID", example = "1")
    private Long id;
 
    @ApiModelProperty(value = "用户名", example = "张三")
    private String username;
 
    @ApiModelProperty(hidden = true)
    @ApiIgnore
    private String password;
 
    // 省略 getter 和 setter 方法
}

在上面的代码中，@ApiModelProperty(hidden = true) 表示该参数是隐藏的，@ApiIgnore 表示忽略该参数。

以上がSpringBoot は Swagger をどのように統合しますか?の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。