Wie integriert SpringBoot Swagger?

Spring Boot ist ein leichtes Open-Source-Framework, das auf dem Spring-Framework basiert. Seine Entstehung vereinfacht die Erstellung und Entwicklung von Spring-Anwendungen erheblich. Im Entwicklungsprozess ist die Schnittstellendokumentation ein sehr wichtiger Teil. Sie erleichtert Entwicklern nicht nur das Anzeigen und Verstehen der Funktionen und Parameter der Schnittstelle, sondern unterstützt auch die Zusammenarbeit von Front-End und Back-End, um die Entwicklungseffizienz zu verbessern.

1. Über Swagger

Swagger ist eine Spezifikation und ein Toolset für RESTful-Schnittstellendokumente. Sein Ziel ist es, das Format und die Spezifikationen von RESTful-Schnittstellendokumenten zu vereinheitlichen. Im Entwicklungsprozess ist die Schnittstellendokumentation ein sehr wichtiger Teil. Sie erleichtert Entwicklern nicht nur das Anzeigen und Verstehen der Funktionen und Parameter der Schnittstelle, sondern unterstützt auch die Zusammenarbeit von Front-End und Back-End, um die Entwicklungseffizienz zu verbessern. Spring Boot kann Swagger integrieren, um automatisch Schnittstellendokumente zu generieren. Durch die Verwendung von Anmerkungen zur Beschreibung von Schnittstellen kann Swagger automatisch Schnittstellendokumente generieren.

2. Swagger-Installation

1. Laden Sie Swagger herunter

Swaggers offizielle Website ist https://swagger.io/, wo wir die neueste Version von Swagger herunterladen können.

2. Swagger installieren

Entpacken Sie einfach den heruntergeladenen Swagger in das angegebene Verzeichnis. Im entpackten Verzeichnis finden wir die Seite swagger-ui.html, die UI-Schnittstelle von Swagger.

3. Verwendung von Swagger

1. Beim Schreiben von Schnittstellen müssen wir Swagger-Anmerkungen verwenden, um Schnittstelleninformationen zu beschreiben. Zu den häufig verwendeten Annotationen gehören:

@Api: wird zur Beschreibung der Klasse oder Schnittstelle der Schnittstelle verwendet
@ApiOperation: wird zur Beschreibung der Methoden der Schnittstelle verwendet
@ApiParam: wird zur Beschreibung der Parameter von verwendet die Schnittstelle
@ApiModel: wird zur Beschreibung des Datenmodells verwendet
@ApiModelProperty: wird zur Beschreibung der Eigenschaften des Datenmodells verwendet
Zum Beispiel schreiben wir eine einfache Schnittstelle:

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

Oben Code, @Api bedeutet, dass die Klasse eine Benutzerschnittstelle ist, @ApiOperation gibt an, dass die Methode eine Schnittstelle zum Abrufen von Benutzerinformationen ist, @ApiParam gibt an, dass der Parameter eine Benutzer-ID ist, und @PathVariable gibt an, dass der Parameter ein Pfadparameter ist.

2. Swagger aktivieren

In Spring Boot können wir Swagger aktivieren, indem wir Swagger-bezogene Abhängigkeiten hinzufügen.

Wir können der Datei pom.xml die folgenden Abhängigkeiten hinzufügen:

<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>

In Spring Boot müssen wir auch eine Konfigurationsklasse hinzufügen, um Swagger zu konfigurieren. Der Code der Konfigurationsklasse lautet wie folgt:

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

Im obigen Code gibt @Configuration an, dass es sich bei der Klasse um eine Konfigurationsklasse handelt, und @EnableSwagger2 gibt an, dass Swagger aktiviert ist. In der api()-Methode konfigurieren wir den gescannten Paketpfad über die `select()-Methode, konfigurieren den Zugriffspfad der Schnittstelle über die paths()-Methode und konfigurieren zugehörige Informationen des Schnittstellendokuments über die apiInfo()-Methode.

3. Sehen Sie sich das Schnittstellendokument an

Nachdem wir die Spring Boot-Anwendung gestartet haben, können wir http://localhost:8080/swagger-ui.html im Browser aufrufen, um das Schnittstellendokument anzuzeigen. Auf der Swagger-UI-Seite können wir alle Schnittstelleninformationen sehen, einschließlich Schnittstellenname, Anforderungsmethode, Anforderungspfad, Anforderungsparameter, Antwortparameter usw.

4. Erweiterte Verwendung von Swagger

1. Beschreiben Sie das Datenmodell

Wir können die Annotationen @ApiModel und @ApiModelProperty verwenden, um das Datenmodell und die Eigenschaften zu beschreiben. Beispielsweise können wir eine User-Klasse schreiben und @ApiModel und

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

für die Klasse verwenden. Im obigen Code gibt @ApiModel an, dass die Klasse ein Datenmodell ist, und @ApiModelProperty gibt an, dass das Attribut ein Attribut des Datenmodells ist und das Wertattribut stellt eine Beschreibung der Eigenschaft dar, und das Beispielattribut stellt einen Beispielwert der Eigenschaft dar. @ApiModel 和 @ApiModelProperty 注解来描述数据模型和属性。例如，我们可以编写一个 User 类，并在类上使用 @ApiModel 和

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

@ApiModelProperty(value = "男")
MALE,

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

在上面的代码中，@ApiModel 表示该类是一个数据模型，@ApiModelProperty 表示该属性是数据模型的一个属性，value 属性表示属性的描述，example 属性表示属性的示例值。

2、描述枚举类型

我们可以使用 @ApiModel 和 @ApiModelProperty

2. Aufzählungstypen beschreiben

Wir können die Annotationen @ApiModel und @ApiModelProperty verwenden, um Aufzählungstypen zu beschreiben. Beispielsweise können wir einen Gender-Aufzählungstyp schreiben und die Annotation @ApiModelProperty für den Aufzählungswert verwenden, um den Aufzählungswert zu beschreiben:

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

Im obigen Code gibt @ApiModel an, dass der Aufzählungstyp eine Aufzählung ist, die das Geschlecht beschreibt. @ApiModelProperty gibt an, dass der Aufzählungswert ein Aufzählungswert ist, der Männer beschreibt, oder ein Aufzählungswert, der Frauen beschreibt.

3. Antwortparameter beschreiben

Wir können @ApiResponses- und @ApiResponse-Annotationen verwenden, um die Antwortparameter der API zu definieren. Beispielsweise können wir eine getUserById()-Methode schreiben und die Annotationen @ApiResponses und @ApiResponse für die Methode verwenden, um die Antwortparameter der Methode zu beschreiben:

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

Im obigen Code stellt @ApiResponses die Antwortparameter der Methode dar, @ ApiResponse gibt die Beschreibung der Antwortparameter an, das Codeattribut gibt den Antwortcode an, das Nachrichtenattribut gibt die Antwortnachricht an und das Antwortattribut gibt das Antwortdatenmodell an.

5. Erweiterte Verwendung von Swagger

1. Konfigurieren Sie globale Parameter

Mit der Methode globalOperationParameters() können wir globale Parameter in der Konfigurationsklasse konfigurieren. Wir können eine Autorisierung durchführen, indem wir einen globalen Autorisierungsparameter konfigurieren🎜

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

🎜Im obigen Code konfigurieren wir einen globalen Autorisierungsparameter für die Autorisierung über die Methode 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 表示忽略该参数。

Das obige ist der detaillierte Inhalt vonWie integriert SpringBoot Swagger?. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!