Swagger는 API를 설계, 문서화, 테스트 및 개발할 수 있는 강력한 도구입니다. 현재는 OpenAPI 사양(OpenAPI Specification, OAS)과 동일한 의미로 사용됩니다. Swagger 도구는 RESTful API를 쉽고 효율적으로 작업할 수 있게 해줍니다.
Swagger를 사용하려면 다음 단계를 참고하세요:
1. Swagger 기본 구성 요소 이해
Swagger는 주로 다음 도구로 구성됩니다:
- Swagger Editor: API 사양을 작성하는 도구.
- Swagger UI: API 문서를 시각적으로 제공하고 테스트할 수 있는 UI.
- Swagger Codegen: API 클라이언트 SDK 또는 서버 코드 생성을 지원.
- Swagger Hub (선택): API 협업 및 호스팅 플랫폼.
2. 설치 및 설정
1) Swagger UI
Swagger UI는 API 문서를 렌더링하고 테스트할 수 있습니다.
설치
- 로컬에서 실행:
- CDN 사용: Swagger UI를 간단히 CDN 링크를 통해 로드할 수도 있습니다:
html
<!DOCTYPE html>
<html>
<head>
<title>Swagger UI</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
});
</script>
</body>
</html>
2) Swagger Editor
Swagger Editor를 사용하여 OpenAPI 파일을 작성할 수 있습니다.
온라인 사용
- Swagger Editor를 사용하여 API 명세를 작성하세요.
로컬 설치
Swagger Editor를 로컬에서 실행하려면:
bash
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start
브라우저에서 http://localhost:8080를 열어 사용합니다.
3. OpenAPI 사양 작성
Swagger는 OpenAPI 형식(JSON 또는 YAML)으로 API를 정의합니다. 기본 예는 다음과 같습니다:
yaml
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Get all users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
type: string
이 파일을 swagger.yaml로 저장하고 Swagger Editor나 Swagger UI에서 열 수 있습니다.
4. API 테스트
Swagger UI는 API를 테스트하는 인터페이스를 제공합니다.
- Try it out 버튼을 클릭해 요청을 전송하고 결과를 확인하세요.
5. Swagger Codegen
Swagger Codegen을 사용하면 OpenAPI 문서에서 클라이언트 SDK 또는 서버 코드를 생성할 수 있습니다.
설치
Swagger Codegen CLI 설치:
bash
npm install -g @openapitools/openapi-generator-cli
사용
OpenAPI 파일에서 Java 서버 코드를 생성하려면:
bash
openapi-generator-cli generate -i swagger.yaml -g spring -o ./output
6. Swagger Hub
Swagger Hub는 팀 협업 및 API 관리 도구입니다.
- 무료 및 유료 버전 제공.
- Swagger 문서를 저장하고 팀과 공유하는 데 유용합니다.
Swagger Hub에서 시작할 수 있습니다.
7. 통합
Swagger는 다양한 백엔드 프레임워크와 통합할 수 있습니다.
- Node.js/Express: swagger-jsdoc, swagger-ui-express 라이브러리를 사용.
- Spring Boot: springdoc-openapi 또는 swagger-springmvc 사용.
- Django: drf-yasg 또는 django-rest-swagger 사용.
Swagger를 특정 환경에 적용하거나 심화 학습이 필요하면 더 자세히 도와드릴 수 있습니다!
-----------------------------------------------------------------------
java swagger 어노테이션
Java에서 Swagger를 사용하여 RESTful API를 문서화하려면 Swagger 어노테이션을 활용할 수 있습니다. 보통 Swagger/OpenAPI 구현 라이브러리로 Springdoc OpenAPI 또는 Swagger 2를 사용합니다. 주요 어노테이션과 사용법은 다음과 같습니다:
1. 주요 의존성 추가
Maven 의존성
Springdoc OpenAPI (Spring Boot 3.x 및 OpenAPI 3 지원)
xml
코드 복사
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
Swagger 2 (Spring Boot 2.x 지원)
xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2. Swagger 어노테이션 주요 사용법
1) 기본 API 문서화
API 전체에 대한 메타데이터를 추가하려면 다음 어노테이션을 사용합니다:
- @OpenAPIDefinition: OpenAPI 3 명세를 정의.
- @Api (Swagger 2): 클래스 수준에서 API를 문서화.
java
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
@OpenAPIDefinition(
info = @Info(
title = "Sample API",
version = "1.0",
description = "Sample API for demonstrating Swagger annotations"
)
)
@RestController
@RequestMapping("/api")
public class SampleController {
}
2) 엔드포인트 문서화
API 메서드에 대한 설명을 추가하려면 다음 어노테이션을 사용합니다:
OpenAPI 3 (Springdoc)
- @Operation: 특정 엔드포인트의 설명 추가.
- @Parameter: 메서드 매개변수 설명.
- @ApiResponse: HTTP 응답에 대한 설명 추가.
- @RequestBody: 요청 본문 설명.
Swagger 2
- @ApiOperation: 메서드 설명.
- @ApiParam: 매개변수 설명.
- @ApiResponses & @ApiResponse: 응답 설명.
java
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/users")
public class UserController {
@Operation(summary = "Get all users", description = "Retrieves a list of all users.")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "Successful operation"),
@ApiResponse(responseCode = "500", description = "Internal server error")
})
@GetMapping
public List<String> getAllUsers() {
return List.of("User1", "User2");
}
@Operation(summary = "Create a user", description = "Adds a new user to the system.")
@PostMapping
public String createUser(
@Parameter(description = "Name of the user to be created") @RequestParam String name) {
return "User " + name + " created.";
}
}
3) 모델 문서화
데이터 모델 클래스에 어노테이션을 추가하여 입력 및 출력 객체를 문서화할 수 있습니다.
OpenAPI 3 (Springdoc)
- @Schema: 모델 필드에 대한 설명.
- @ExampleObject: 예제 데이터 제공.
Swagger 2
- @ApiModel: 클래스 수준에서 모델 설명.
- @ApiModelProperty: 필드 설명.
java
import io.swagger.v3.oas.annotations.media.Schema;
@Schema(description = "User entity")
public class User {
@Schema(description = "Unique identifier of the user", example = "1")
private Long id;
@Schema(description = "Name of the user", example = "John Doe")
private String name;
@Schema(description = "Email of the user", example = "john.doe@example.com")
private String email;
// Getters and Setters
}
4) 요청/응답 명세
API 요청과 응답 데이터를 명시적으로 문서화하려면 OpenAPI 어노테이션을 사용합니다.
java
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/products")
public class ProductController {
@Operation(summary = "Get a product by ID")
@ApiResponse(
responseCode = "200",
description = "Product retrieved successfully",
content = @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class))
)
@GetMapping("/{id}")
public Product getProductById(@PathVariable Long id) {
return new Product(id, "Sample Product");
}
}
class Product {
private Long id;
private String name;
// Constructor, Getters, and Setters
public Product(Long id, String name) {
this.id = id;
this.name = name;
}
}
3. Swagger UI 확인
Swagger UI 경로
- Springdoc OpenAPI: 기본적으로 Swagger UI는 /swagger-ui.html 또는 /v3/api-docs에서 확인할 수 있습니다.
- Swagger 2: 기본 경로는 /swagger-ui.html입니다.
4. 팁
- Springdoc OpenAPI와 Swagger 2 비교:
- Springdoc OpenAPI는 최신 OpenAPI 3 사양을 지원하며, Spring Boot 3과 호환성이 뛰어납니다.
- Swagger 2는 OpenAPI 2 사양 기반으로, 기존 Spring Boot 2.x 프로젝트에 적합합니다.
- Swagger UI의 동작을 커스터마이즈하려면 application.properties에서 설정을 변경할 수 있습니다.
properties
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui
| 