SpringBoot統合インターフェース管理ツールSwaggerの使い方

1. Swagger の概要

Swagger は一連の RESTful API ツールであり、Swagger を通じてプロジェクトのインタラクティブなドキュメントの取得、クライアント SDK の自動生成などの機能を利用できます。

Swagger の目標は、REST API 用の言語に依存しない標準インターフェイスを定義して、人やコンピュータがソース コードやドキュメントを見られたり、ネットワーク トラフィックの検出を通過できないようにすることです。さまざまなサービスの機能を理解します。 Swagger を通じてサービスが定義されている場合、コンシューマーは少量の実装ロジックを使用してリモート サービスと対話できます。

2. Springboot は swagger を統合します

Spring Boot を使用して Swagger を統合するというアイデアは、アノテーションを使用して API ドキュメントに表示する必要がある情報をマークすることです。プロジェクト内でマークされた注釈を使用して情報をマークし、対応する API ドキュメントを生成します。 Swagger は世界で最も人気のある API ツールとして知られています。API 管理の完全なソリューションを提供します。API ドキュメント管理で考慮する必要がある要素は基本的に含まれています。ここでは、最もよく使用されるカスタマイズ内容について説明します。

1. Swagger 座標の追加

Spring Boot は Swagger 3 を統合します。これは非常に簡単で、依存関係を導入し、基本的な設定を行うだけです。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. Swagger Helloword の実装

2.1. springboot プロジェクトの作成

@EnableOpenApi アノテーションをスタートアップ クラスに追加して、Swagger API ドキュメント関数を有効にします

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi  //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
    }

}

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

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
public class SwaggerController {
    @GetMapping ("hello")
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

2.3. アクセス アドレス

http://localhost:8080/swagger-ui/index.html

##3. 一般的に使用される設定アノテーション

Swagger は、インターフェイス名、リクエスト メソッド、パラメーター、戻り情報などを含むドキュメントをインターフェイスが生成することをアノテーションを通じて示します。

1、

Api アノテーション、および ApiOperation アノテーション

• @Api

は、クラスが Swagger リソースであることを示すためにクラスで使用されます。 @API には、 value と tags という 2 つの属性があります。

生成された API ドキュメントはタグに従って分類されます。端的に言えば、このコントローラーのすべてのインターフェイスによって生成されたインターフェイス ドキュメントはタグ リストの下にあります。タグに複数の値がある場合、複数のリストが生成されます。各リストには、タグなどのすべてのインターフェース

値関数が表示されますが、複数の値を持つことはできません

语法:
  @Api(tags = "用户操作")
  或
  @Api(tags = {"用户操作","用户操作2"})

• @ApiOperation

http リクエストの操作を示すメソッドで使用されます

语法:
    @ApiOperation(value = "", 
                  notes = "", 
                  response = )
属性说明：
  value：方法说明标题
  notes：方法详细描述
  response：方法返回值类型

ケース: @Api および @ApiOperation を使用して API ドキュメントを生成します

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

2,

ApiImplicitParams アノテーションと ApiImplicitParam

@ApiImplicitParams アノテーションと @ApiImplicitParam は、メソッド内の非オブジェクト パラメーター (パラメーター バインディング) に使用されます。到着時に使用されます。

语法:
@ApiImplicitParams(value = {
     @ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue  = "")
})

属性说明：
    name:形参名称
    value:形参的说明文字
    type:形参类型
    required:该参数是否必须  true|false
    paramType: 用于描述参数是以何种方式传递到 Controller 的，它的值常见有： path, query, body 和 header 
        path 表示参数是『嵌在』路径中的，它和 @PathVariable 参数注解遥相呼应；
    	query 表示参数是以 query string 的形式传递到后台的（无论是 get 请求携带在 url 中，还是 post 请求携带在请求体中），它和 @RequestParam 参数注解遥相呼应；
    	header 表示参数是『藏在』请求头中传递到后台的，它和 @RequestHeader 参数注解遥相呼应的。
    	form 不常用.
    defaultValue :参数默认值

注: @ApiImplicitParam の name 属性は、@RequestParam または @PathVariable の値をエコーする必要があります。

ケース: @ApiImplicitParams アノテーションと @ApiImplicitParam を使用してメソッド パラメーターを記述します

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    @ApiImplicitParams(value ={
            @ApiImplicitParam(name="param1",
                    value = "参数名1",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值1" ),
            @ApiImplicitParam(name="param2",
                    value = "参数名2",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值2" )
    })
    public String hello(String param1,String param2) {
        return "hello swagger"+" param1为:"+param1+"param2为"+param2;
    }
}

3、ApiModel アノテーションと ApiModelProperty

#@ApiModel

• は、エンティティ クラスでクラスを記述するために使用され、エンティティ クラスでのパラメーター受信命令に使用されます。

  @ApiModel("用户类")
  @Data
  public class Users {
  
      @ApiModelProperty(value = "编码：主键")
      private Integer id;
  
      @ApiModelProperty(value = "用户名")
      private String username;
  
      @ApiModelProperty(value = "密码")
      private String password;
  
  }

  4. ApiResponse と ApiResponses

@ApiResponses アノテーションと @ApiResponse アノテーションは、HTTP リクエストの応答を記述するためにコントローラー メソッドにマークされます

/**
     * 添加用户
     *
     * @param user
     * @return
     */
    @PostMapping("/add")
    @ApiOperation(value = "添加用户",notes = "添加用户信息",response = ResponseResult.class)
    @ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
            	    @ApiResponse(code = 500, message = "添加失败", response = ResponseResult.class) })
    public ResponseResult<Void> addUser(@RequestBody User user) {
        //获得生成的加密盐
        user.setSalt(SaltUtils.getSalt());
        int n = userService.addUser(user);
        if (n > 0) {
            return new ResponseResult<Void>(200, "添加成功");
        }
        return new ResponseResult<Void>(500, "添加失败");
    }

5. SwaggerConfig 構成クラスを作成します

SwaggerConfig に 2 つのメソッドを追加します: (1 つのメソッドは、もう 1 つのメソッドの補助的な準備を行うためのもの)

api() メソッドは @Bean を使用し、次の場所で初期化されます。起動すると、インスタンス Docket (Swagger API 概要オブジェクト) が返されます。ここで注意する必要があるのは、.apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz")) がスキャンする必要があるパッケージ パスを指定していることです。このパスの下のコントローラー クラスは Swagger API ドキュメントを自動的に生成します。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置类
 */
@Configuration  //项目启动时加载此类
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 此处自行修改为自己的 Controller 包路径。
                .apis(RequestHandlerSelectors.basePackage("com.lps.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("阿水的项目接口文挡")
                .description("阿水的 Project Swagger2 UserService Interface")  //说明信息
                .termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文档生成的主页地址
                .version("1.0")  //文档版本
                .build();
    }
}

apiInfo() メソッドの設定は比較的重要です。メイン設定ページに表示される基本情報には、タイトル、説明、バージョン、利用規約などが含まれます。ApiInfo クラスのソース コードを見ると、ライセンス サポートなどのその他の構成も見つかります。

4. Springsecurity は swagger

4.1 を統合し、リリース アドレス

#

  http.authorizeRequests().antMatchers( "/swagger-ui.html",
                "/swagger-ui/*",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**").permitAll()
                .anyRequest().authenticated();

4.2 を構成し、UI

# を置き換えます。 ##上記のプロセス全体は完了しましたが、生成されたインターフェイスのドキュメント ページは実際、多くの人が気に入らず、中国人の使用習慣と一致していないと感じています。そのため、一部の専門家は他のドキュメント ページを提供しています。 UI テスト ページ。このページの用途は非常に広範です。

次の依存関係をインポートし、プロジェクトを再起動して、アドレス http://localhost:8080/doc.html

	<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

にアクセスします。

以上がSpringBoot統合インターフェース管理ツールSwaggerの使い方の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。