Bagaimanakah SpringBoot menyepadukan Swagger?

Spring Boot ialah rangka kerja sumber terbuka yang ringan berdasarkan rangka kerja Spring. Kemunculannya sangat memudahkan pembinaan dan pembangunan aplikasi Spring. Dalam proses pembangunan, dokumentasi antara muka adalah bahagian yang sangat penting Ia bukan sahaja memudahkan pembangun untuk melihat dan memahami fungsi dan parameter antara muka, tetapi juga membantu pembangunan bahagian hadapan dan bahagian belakang bekerjasama untuk meningkatkan kecekapan pembangunan.

1. Perihal Swagger

Swagger ialah spesifikasi dan set alat untuk dokumen antara muka RESTful. Dalam proses pembangunan, dokumentasi antara muka adalah bahagian yang sangat penting Ia bukan sahaja memudahkan pembangun untuk melihat dan memahami fungsi dan parameter antara muka, tetapi juga membantu pembangunan bahagian hadapan dan bahagian belakang bekerjasama untuk meningkatkan kecekapan pembangunan. Spring Boot boleh menyepadukan Swagger untuk menjana dokumen antara muka secara automatik. Dengan menggunakan anotasi untuk menerangkan antara muka, Swagger boleh menjana dokumen antara muka secara automatik.

2. Pemasangan Swagger

1 Muat turun Swagger

Tapak web rasmi Swagger ialah https://swagger.io/, kami boleh memuat turun versi terkini Swagger di sini. .

2. Pasang Swagger

Hanya nyahzip Swagger yang dimuat turun ke direktori yang ditentukan ini agak mudah. Dalam direktori unzip, kita boleh menemui halaman swagger-ui.html, iaitu antara muka UI Swagger.

3. Penggunaan Swagger

1. Menulis antara muka

Apabila menulis antara muka, kita perlu menggunakan anotasi Swagger untuk menerangkan maklumat antara muka. Anotasi yang biasa digunakan termasuk:

• @Api: Kelas atau antara muka yang digunakan untuk menerangkan antara muka

• @ApiOperation: Kaedah yang digunakan untuk menerangkan antara muka

• @ApiParam: digunakan untuk menerangkan parameter antara muka

• @ApiModel: digunakan untuk menerangkan model data

• @ApiModelProperty: Sifat yang digunakan untuk menerangkan model data

Sebagai contoh, kami menulis antara muka yang ringkas:

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

Dalam kod di atas, @Api mewakili Kelas ialah antara muka pengguna, @ApiOperation menunjukkan bahawa kaedah adalah antara muka untuk mendapatkan maklumat pengguna, @ApiParam menunjukkan bahawa parameter ialah ID pengguna, dan @PathVariable menunjukkan bahawa parameter ialah parameter laluan.

2. Dayakan Swagger

Dalam Spring Boot, kami boleh mendayakan Swagger dengan menambahkan kebergantungan berkaitan Swagger.
Kami boleh menambah kebergantungan berikut dalam fail 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>

Dalam Spring Boot, kami juga perlu menambah kelas konfigurasi untuk mengkonfigurasi Swagger. Kod kelas konfigurasi adalah seperti berikut:

@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();
    }
}

Dalam kod di atas, @Configuration menunjukkan bahawa kelas ialah kelas konfigurasi dan @EnableSwagger2 menunjukkan bahawa Swagger didayakan. Dalam kaedah api(), kami mengkonfigurasi laluan pakej yang diimbas melalui kaedah `select(), mengkonfigurasi laluan capaian antara muka melalui kaedah paths() dan mengkonfigurasi maklumat berkaitan dokumen antara muka melalui kaedah apiInfo().

3. Lihat dokumen antara muka

Selepas memulakan aplikasi Spring Boot, kita boleh melawati http://localhost:8080/swagger-ui.html dalam penyemak imbas untuk melihat dokumen antara muka. Dalam halaman UI Swagger, kita boleh melihat semua maklumat antara muka, termasuk nama antara muka, kaedah permintaan, laluan permintaan, parameter permintaan, parameter tindak balas, dsb.

4. Penggunaan lanjutan Swagger

1. Huraikan model data

Kita boleh menggunakan anotasi @ApiModel dan @ApiModelProperty untuk menerangkan model dan atribut data. Sebagai contoh, kita boleh menulis kelas Pengguna dan menggunakan @ApiModel dan

@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 方法
}

pada kelas Dalam kod di atas, @ApiModel menunjukkan bahawa kelas itu adalah model data dan @ApiModelProperty menunjukkan bahawa sifat itu adalah. model data, atribut nilai mewakili perihalan atribut, dan atribut contoh mewakili nilai contoh atribut.

2. Menerangkan jenis penghitungan

Kita boleh menggunakan @ApiModel dan @ApiModelProperty anotasi untuk menerangkan jenis penghitungan. Sebagai contoh, kita boleh menulis jenis penghitungan Jantina dan menggunakan anotasi @ApiModelProperty pada nilai penghitungan untuk menerangkan nilai penghitungan:

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

@ApiModelProperty(value = "男")
MALE,

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

Dalam kod di atas, @ApiModel menunjukkan bahawa jenis penghitungan ialah jenis penghitungan yang menerangkan jantina. @ApiModelProperty menunjukkan bahawa nilai penghitungan ialah nilai penghitungan yang menerangkan lelaki atau nilai penghitungan yang menggambarkan wanita.

3. Huraikan parameter respons

Kami boleh menggunakan anotasi @ApiResponses dan @ApiResponse untuk mentakrifkan parameter respons API. Sebagai contoh, kita boleh menulis kaedah getUserById() dan menggunakan anotasi @ApiResponses dan @ApiResponse pada kaedah untuk menerangkan parameter tindak balas kaedah:

@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 查询用户信息 
}

Dalam kod di atas, @ApiResponses mewakili respons bagi Parameter kaedah, @ApiResponse mewakili perihalan parameter respons, atribut kod mewakili kod respons, atribut mesej mewakili mesej respons, dan atribut respons mewakili model data respons.

5. Penggunaan lanjutan Swagger

1 Konfigurasikan parameter global

Dengan menggunakan kaedah globalOperationParameters(), kami boleh mengkonfigurasi parameter global dalam kelas konfigurasi. Kami boleh memberi kebenaran dengan mengkonfigurasi parameter Kebenaran global

@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();
    }
 
}

Dalam kod di atas, kami mengkonfigurasi parameter Kebenaran global untuk kebenaran melalui kaedah 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 表示忽略该参数。

Atas ialah kandungan terperinci Bagaimanakah SpringBoot menyepadukan Swagger?. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!