Swagger Opendoc API

Swagger..

 

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

 

개인적으로 Postman을 사용했었을 때 굳이 Postman 말고 다른 걸 사용할 필요가 있을까 하는 생각이었다.

하지만 회사에 들어가고 나서 선임이 말해준 이유는 충분히 Postman이 아닌 다른 API플랫폼을 찾기엔 충분했다.

 

Postman의 경우 기업이 운영하기에 사용량이 많아지면 '유료'로 가격이 책정된다는 것이었다.

맨날 혼자 사이드 프로젝트를 하던 사람에겐 '아 맞다' 한 이유였다.

 

Swagger의 경우에도 크게 SpringFox와 SpringDoc으로 나뉘어 있지만 SpringFox의 경우 업데이트가 2020년 이후로 멈춰있어

SpringDoc을 사용해서 개발하는 게 옳다고 본다.

 

https://github.com/springdoc/springdoc-openapi

GitHub - springdoc/springdoc-openapi: Library for OpenAPI 3 with spring-boot

요즘은 굳이 다른 블로그를 안 보고 직접 문서를 번역기로 돌려 이해하는 것에 재미 들렸다.

 

---

환경설정

• Java 11
• SpringBoot 2.6.8
• Spring Web
• Lombok

Java 17 + SpringBoot 3.x.x 버전은 이미 Github에 잘 정리되어 있다.

나의 경우 아직 Java 11과 스프링부트 3 이하 버전의 프로젝트에 추가개발을 맡게 되어 이렇게 진행하려고 한다.

 

 

application.yml

springdoc:
  swagger-ui:
    path: /swagger-ui.html

 

 

build.gradle

    // Swagger OpenDoc Api
    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.9'

 

 

Controller

package com.example.swaggertemplate.controller;

import com.example.swaggertemplate.dto.TestDTO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @name : TestController
 * @author : Mo-Greene
 * @date : 2023/07/18
 * 스웨거 테스트
 */
@RestController
public class TestController {

    @GetMapping("/api")
    @Operation(summary = "Swagger 테스트", description = "스웨거 테스트")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "Success"),
            @ApiResponse(responseCode = "400", description = "Fail")
    })
    public void api(TestDTO testDTO) {
        System.out.println("testDTO = " + testDTO);
    }
}

 

 

TestDTO

package com.example.swaggertemplate.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
public class TestDTO {

    @Schema(description = "Swagger Content", example = "swagger example")
    private String content;
}

 

따로 SwaggerConfig를 사용해 설정을 잡아주지 않아도 되는 점이 좋은 것 같다.

 

 

결과화면

 

API 문서화 작업은 그만큼 시간이 들어가는 작업이다.

혼자서 작업한다면 상관없지만 분명 클라이언트 혹은 이 코드를 참고하게 될 다른 개발자들에게 전해줄 수 있는 문서가 될 수 있기에

시간을 할애해서라도 작업해 두는 것을 권한다.