Swagger 실습해보기

[codemaker-kim]

Swagger에 대한 기초 환경을 설정했다.

GPT 피셜로는 Spring doc Open API 와 Springfox가 있다고 하는데, 여기서는 꾸준히 업데이트가 진행되고 있는 Spring doc을 사용해볼 것이다.

우선 추가되는 의존성 코드는 다음과 같다.

     // Swagger 사용을 위한 의존성 추가
    // 지금 사용하는 Spring doc OPEN API는 Swagger UI를 자동으로 생성함.
    implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

서버를 실행했을 때, Swagger UI의 확인은 아래 경로에서 가능하다.

http://localhost:8080/swagger-ui

당연하지만 처음에는 404(not fond) 에러가 뜬다.

끝인줄 알았는데 추가로 yml 파일 설정이 있어서 간단하게 해보았다.

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

[codemaker-kim]

Swagger를 사용해보기 위한 간단한 API 컨트롤러를 구현해보았다.

// Swagger 학습용 간단한 컨트롤러
@RestController
@RequestMapping("/api/users")
public class UserController {

    /*
    * Swagger 사용을 위하여 사용된 어노테이션들 정리
    * @Operation : 특정 API에 대한 설명을 제공할 수 있음.
    * @ApiResponses : API가 반환할 수 있는 모든 응답을 문서화.
    * @ApiResponse : @ApiResponses 내에서 응답 코드와 간단한 설명을 포함해 응답을 설명함.
    * */

    @Operation(summary = "Get all users")
    @ApiResponses(value ={
            @ApiResponse(responseCode = "200", description = "Successfully get list"),
            @ApiResponse(responseCode = "500", description = "Internal Server Error")

    })
    @GetMapping
    public List<String> getAllUsers(){
        return Arrays.asList("수민", "케인", "엄준식");
    }

    @Operation(summary = "Get a user by Id")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Successfully get user"),
            @ApiResponse(responseCode = "400", description = "User not found")
    })
    @GetMapping("{id}")
    public String getUserById(@PathVariable int id){
        List<String> users = Arrays.asList("수민", "케인", "엄준식");
        if(id < 0 || id >= users.size())
            return "User not found";
        return users.get(id);
    }

    @Operation(summary = "Add new User")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "201", description = "User created Successfully"),
            @ApiResponse(responseCode = "400", description = "Invalid input")
    })
    @PostMapping
    public String addUser(@RequestBody String name) {
        return "User " + name + " added successfully";
    }
}

[codemaker-kim]

오잉 웬일인지 gpt가 알려준 링크로 접속해보니 여전히 404가 뜨고 있다. 뭔가 다른 문제가 있는게 분명하다.

찾아보니 위에서 적은 내용은 스프링부트 2.x.x 버전에서 사용되던 의존성 추가 방식이고,

최신 버전은 아래와 같이 의존성을 추가한다고 한다.

    //3.3.4 버전에 맞춘 의존성은 아래와 같다고 하네용
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

하지만 어째서인지 여전히 링크로 접속이 안된다. 왜일까?

알고보니 yml 파일에 꼭 추가해야 하는 내용이 있었다. 그것은 바로...

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

#추가한 내용
server:
  port: 8080

서버의 포트를 추가해주어야 됬던 것이다..사실 사소하게 여기고 그냥 추가 안해도 되겠지 싶어서 추가를 안했는데 저걸 빼버리면 계속 404 에러가 발생했다. 위에서는 정상적인건 줄 알고 그냥 진행했는데 앞으로는 사소한 것도 꼭 확인해보는 습관을 들여야겠다.

잘 실행된 Swagger ui의 모습

[codemaker-kim]

드롭다운을 눌러보면

이런 식으로 API에 대한 정보가 보이고, try it out 버튼을 통해, API를 직접 쏴볼수도 있다.

이번에 해본건 정말 간단한 예제라서 따로 Swagger 사용을 위한 config도 추가하진 않았지만,

다음에는 config 추가하는 이유나 그 외에 코드 설정에 대해 찾아보아야겠다.