Java API 개발에서 Swagger 사용에 대한 자세한 소개

Swagger는 Java API 개발에 매우 ​​유용한 도구입니다. Swagger는 RESTful 웹 서비스를 설명, 설계 및 생성하기 위한 오픈 소스 API 프레임워크입니다. 개발자가 API 및 매개변수를 설명하는 데 도움이 되는 주석 세트를 제공합니다. 이 기사에서는 Java API 개발에서 Swagger를 사용하는 방법을 자세히 설명합니다.

1. Swagger 설치

Swagger는 Maven을 사용하여 Java 프로젝트에 통합될 수 있습니다. 다음 Maven 종속성을 사용하여 프로젝트에 Swagger를 추가할 수 있습니다.

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

또한 Swagger UI를 생성하려면 다음 종속성을 추가해야 합니다.

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

2. Java 애플리케이션에서 Swagger 구성

, 다음을 구성해야 합니다. 멋진. 이를 위해 Swagger를 초기화하는 구성 클래스를 생성할 수 있습니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }
}

위 코드에서는 Swagger의 기본 인터페이스인 Docket Bean을 정의했습니다. 이를 사용하여 Swagger API 유형을 지정하고 이를 애플리케이션의 URL과 매핑합니다.

3. Swagger 주석 추가

이제 Java API에 Swagger 주석을 추가할 수 있습니다. 다음은 일반적으로 사용되는 Swagger 주석과 그 용도입니다.

• @Api: 전체 API를 설명하는 데 사용됩니다.
• @ApiOperation: API 작업을 설명하는 데 사용됩니다.
• @ApiParam: 작업 매개변수를 설명하는 데 사용됩니다.
• @ApiModel: API를 제공하는 데 사용되는 모델 속성입니다.
• @ApiModelProperty: API 모델을 설명하는 데 사용되는 속성입니다.

이러한 주석은 클래스, 메소드, 필드 및 메소드 매개변수에 배치될 수 있으며 value 및 Notes 속성을 사용하여 API 주석에 대한 정보를 제공할 수 있습니다.

예를 들어 다음 코드 조각이 있는 경우:

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

Swagger 주석을 사용하여 getUser 메서드를 설명할 수 있습니다.

@RestController
@RequestMapping("/users")
@Api(value="用户管理", tags="用户管理")
public class UserController {
 
    @GetMapping("/{id}")
    @ApiOperation(value="获取用户信息", notes="根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

위 코드에서는 @Api 및 @ApiOperation 주석을 사용했습니다. @Api 주석은 이름과 레이블을 포함한 전체 API를 설명하는 데 사용됩니다. @ApiOperation 주석은 작업 이름과 작업에 대한 몇 가지 참고 사항을 설명하는 데 사용됩니다.

4. Swagger UI 생성

이제 Java 애플리케이션이 Swagger 및 Swagger 주석으로 구성되었으므로 Swagger UI를 사용하여 API를 표시하고 테스트할 수 있습니다.

이를 수행하려면 SwaggerConfig 클래스의 @Bean 주석 아래에 다음 줄을 추가하면 됩니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }

    @Bean
    public UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
            .docExpansion(DocExpansion.LIST)
            .build();
    }
}

이렇게 하면 Swagger UI 구성을 위한 uiConfig() Bean이 추가됩니다. 위의 코드를 사용하여 DocExpansion을 LIST로 설정하여 UI에서 기본적으로 모든 작업이 확장되도록 했습니다.

5. 애플리케이션 실행

이제 Swagger 및 Swagger 주석을 구성하고 SwaggerConfig 클래스에 Swagger UI를 생성했습니다. 다음 명령을 사용하여 애플리케이션을 시작할 수 있습니다.

$ mvn spring-boot:run

Swagger의 기본 설정에 따라 브라우저에서 Swagger UI에 액세스할 수 있습니다. http://localhost:8080/swagger-ui.html로 이동하면 Swagger UI에 이미 API가 표시되어 있는 것을 볼 수 있습니다.

6. API 테스트

마지막으로 Swagger UI를 사용하여 API를 테스트할 수 있습니다. "사용해 보기" 버튼을 클릭하면 Swagger UI가 자동으로 API에 요청을 보내고 UI에서 응답을 볼 수 있습니다.

이 글에서는 Java API 개발에 Swagger를 활용하는 방법을 소개했습니다. Swagger를 사용하면 API를 쉽게 설명하고 테스트할 수 있으며, 읽고 사용하기 쉬운 문서를 생성할 수 있습니다. Java 개발자라면 Swagger를 사용해 API 개발 및 테스트를 단순화하는 것이 좋습니다.

위 내용은 Java API 개발에서 Swagger 사용에 대한 자세한 소개의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!