Swagger를 사용하여 API 문서를 생성하는 방법은 무엇입니까?

웹 애플리케이션의 급속한 발전과 함께 API 문서화는 점점 더 중요해지고 있습니다. API 문서는 개발자가 API 사용 방법과 매개변수를 이해하고 시간과 리소스 낭비를 줄이는 데 도움을 주기 위해 설계되었습니다. 그러나 API 문서를 수동으로 작성하는 것은 번거롭고 시간이 많이 걸릴 수 있습니다. 현재 Swagger는 개발자에게 강력한 도구가 됩니다. Swagger는 읽기 쉬운 대화형 API 문서를 자동으로 생성할 수 있는 널리 사용되는 API 문서 도구입니다. 이 기사에서는 Swagger를 사용하여 API 문서를 자동으로 생성하는 방법을 소개했습니다.

Swagger란 무엇인가요?

Swagger는 개발자가 RESTful 웹 서비스를 구축, 설계, 설명 및 소비하는 데 도움이 되는 오픈 소스 도구 세트입니다. Swagger를 사용하면 API 작업을 설명하는 YAML 또는 JSON 형식을 사용하여 API 문서를 작성하고 읽기 쉽고 상호 작용할 수 있는 인터페이스 문서를 생성할 수 있습니다.

Swagger는 Java, C#, Python 및 Ruby와 같은 여러 프로그래밍 언어와 프레임워크를 지원합니다. 또한 Spring, Express, Django 등을 포함한 많은 기존 API 프레임워크와 통합할 수도 있습니다.

Swagger를 사용하여 API 문서를 생성하려면 먼저 Swagger UI를 설치해야 합니다. Swagger UI는 API와 독립적이고 Swagger 사양을 따르는 대화형 API 문서 웹 사이트입니다. API 문서를 시각화하기 위한 아름다운 인터페이스를 제공하고 API 호출의 자동화된 시도를 지원합니다.

1단계: Swagger 구성

Swagger를 사용하려면 먼저 Swagger 패키지를 다운로드해야 합니다. 이 패키지는 Swagger 웹 사이트에서 얻거나 종속성 관리자를 사용하여 다운로드할 수 있습니다.

Java Spring Boot 프로젝트에서 Swagger API를 구성하려면 Maven 종속성에 다음 Swagger 종속성을 추가해야 합니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox-swagger2.version}</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox-swagger-ui.version}</version>
</dependency>

where ${springfox-swagger2.version} 및 ${springfox-swagger-ui.version} Swagger 버전 번호를 나타냅니다. 구성 파일 application.properties에서 swagger를 활성화합니다.

#开启swagger
swagger.enabled = true

2단계: Swagger 주석 작성

Swagger는 주석을 사용하여 API의 작업 및 매개 변수를 설명합니다. Swagger가 문서를 올바르게 구문 분석하고 생성하여 Swagger UI에 표시할 수 있도록 API 컨트롤러 클래스 및 해당 메서드 상단에 Swagger 주석을 추가합니다.

다음은 몇 가지 샘플 주석입니다.

1. @Api: API의 설명 정보를 추가하는 데 사용됩니다.

@Api(value="User",tags={"User 操作接口"})
@Controller
@RequestMapping("/users")
public class UserController {
    // ...
}

2. @ApiOperation: API 작업의 설명 정보를 추가하는 데 사용됩니다.

@ApiOperation(value = "获取用户列表", notes = "")
@GetMapping(value = "/list")
public Result getUserList() {
    List<User> userList = userService.listUser();
    return Result.success(userList);
}

3. @ApiParam: 추가하는 데 사용됩니다. API 작업 매개변수 설명 정보

@ApiOperation(value = "获取用户信息", notes = "根据url的id来获取用户详细信息")
@GetMapping(value = "/{id}")
public Result getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    User user = userService.getUserById(id);
    return Result.success(user);
}

3단계: 애플리케이션 시작 및 Swagger UI에 액세스

Swagger 주석 작성을 완료한 후 브라우저를 사용하여 Swagger UI의 주소를 엽니다. API를 기반으로 시각적 API 문서를 자동으로 작성합니다.

Swagger UI의 기본 주소는 http://localhost:8080/swagger-ui.html

Swagger UI 인터페이스에서 API 개요, 다양한 API 인터페이스 설명, 요청 및 응답 매개변수를 볼 수 있습니다. 그리고 일부 테스트 코드 등 이는 개발자가 API를 더 잘 이해하고 사용하는 데 도움이 될 수 있습니다.

요약

Swagger는 쉽게 읽고 상호 작용할 수 있는 API 문서를 자동으로 생성할 수 있는 강력한 API 문서 도구입니다. Swagger를 사용하면 API 개발의 효율성과 품질을 향상시키고 API 문서를 수동으로 작성하는 데 필요한 시간과 리소스를 줄일 수 있습니다. 위의 단계를 따르면 Swagger를 사용하여 쉽게 API 문서를 자동으로 생성할 수 있습니다.

위 내용은 Swagger를 사용하여 API 문서를 생성하는 방법은 무엇입니까?의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!