SpringBoot는 Swagger를 어떻게 통합합니까?

Spring Boot는 Spring 프레임워크를 기반으로 하는 경량 오픈 소스 프레임워크로, Spring 애플리케이션의 구성과 개발을 크게 단순화합니다. 개발 프로세스에서 인터페이스 문서화는 개발자가 인터페이스의 기능과 매개변수를 보고 이해하는 데 도움이 될 뿐만 아니라 프런트엔드와 백엔드 개발이 함께 작동하여 개발 효율성을 높이는 데도 도움이 됩니다.

1. Swagger 정보

Swagger의 목표는 RESTful 인터페이스 문서의 형식과 사양을 통합하는 것입니다. 개발 프로세스에서 인터페이스 문서화는 개발자가 인터페이스의 기능과 매개변수를 보고 이해하는 데 도움이 될 뿐만 아니라 프런트엔드와 백엔드 개발이 함께 작동하여 개발 효율성을 높이는 데도 도움이 됩니다. Spring Boot는 Swagger를 통합하여 인터페이스 문서를 자동으로 생성할 수 있습니다. Swagger는 주석을 사용하여 인터페이스를 설명함으로써 자동으로 인터페이스 문서를 생성할 수 있습니다.

2. Swagger 설치

1. Swagger 다운로드

Swagger의 공식 웹사이트는 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 및 @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

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

@ApiModelProperty(value = "男")
MALE,

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

를 사용할 수 있습니다. 위 코드에서 @ApiModel은 클래스가 데이터 모델임을 나타내고 @ApiModelProperty는 속성이 데이터 모델의 속성임을 나타냅니다. , value 속성은 속성에 대한 설명을 나타내고, example 속성은 속성의 예시 값을 나타냅니다.

2. 열거 유형 설명

@ApiModel 및 @ApiModelProperty 주석을 사용하여 열거 유형을 설명할 수 있습니다. 예를 들어 성별 열거 유형을 작성하고 열거 값에 @ApiModelProperty 주석을 사용하여 열거 값을 설명할 수 있습니다.

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

위 코드에서 @ApiModel은 열거 유형이 성별 열거 유형을 설명하는 열거임을 나타냅니다. @ApiModelProperty는 열거형 값이 남성을 설명하는 열거형 값이거나 여성을 설명하는 열거형 값임을 나타냅니다.

3. 응답 매개변수 설명

@ApiResponses 및 @ApiResponse 주석을 사용하여 API의 응답 매개변수를 정의할 수 있습니다. 예를 들어 getUserById() 메서드를 작성하고 메서드에 @ApiResponses 및 @ApiResponse 주석을 사용하여 메서드의 응답 매개 변수를 설명할 수 있습니다.

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

위 코드에서 @ApiResponses는 메서드의 응답 매개 변수 @를 나타냅니다. ApiResponse 응답 매개변수에 대한 설명을 나타내며, code 속성은 응답 코드, message 속성은 응답 메시지, response 속성은 응답 데이터 모델을 나타냅니다.

5. Swagger의 고급 사용

1. 전역 매개변수 구성🎜🎜globalOperationParameters() 메서드를 사용하여 구성 클래스에서 전역 매개변수를 구성할 수 있습니다. 전역 Authorization 매개변수를 구성하여 인증할 수 있습니다🎜

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

🎜위 코드에서는 globalOperationParameters() 메서드를 통해 인증을 위한 전역 Authorization 매개변수를 구성합니다. 🎜

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 중국어 웹사이트의 기타 관련 기사를 참조하세요!