Spring Boot : Swagger 적용 및 기본 사용법

swagger는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크입니다. API를 개발할때 웹에서 쉽게 확인 할 수 있기때문에 아주 유용한 도구입니다.

maven을 사용 할 경우 pom.xml에 다음을 추가해주고 필요한 경우 application.yml에 다음 내용을 추가하면 됩니다. application.yml에 들어가는 내용은 swagger 환경설정 내용이기에 생략하셔도 됩니다.

pom.xml

<!--swagger-->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.6.13</version>
</dependency>

application.yml

springdoc:
  version: '@project.version@'
  #api-docs:
   #path: /api-docs
  #default-consumes-media-type: application/json
  #default-produces-media-type: application/json
  #swagger-ui:
    #operations-sorter: alpha
    #tags-sorter: alpha
    #path: /swagger-ui.html
    #disable-swagger-default-url: true
    #display-query-params-without-oauth2: true
    #doc-expansion: none
  #paths-to-match:
    #- /api/**

그리고 swagger화면에서 표시될 내용을 설정해주는 파일을 만들어줍니다.

OpenApiConfig.java

package com.tistory.devnam;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;

@Configuration
public class OpenApiConfig {
	
	@Bean
	public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion){
		Info info = new Info().title("DEVNAM API")
				.version(appVersion)
				.description("DEVNAM.TISTORY.COM API")
				.contact(new Contact().name("By.DevNam")
			    .url("https://devnam.tistory.com/")
				);	
		
		return new OpenAPI().components(new Components()).info(info);
	}

}

CallApiController.java

이제 swagger를 사용하려면 @Tag @Operation @Schema 어노테이션을 입력하여 사용하시면됩니다.

package com.tistory.devnam;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api")
@Tag(name="Call Api", description="Api 테스트")
public class CallApiController {
	
    @Autowired
    JdbcTemplate jdbcTemplate;
    
    @Operation(summary="사용자 이름을 조회한다.", description="파라미터 id 필수")
    @GetMapping("/usr/name")
    public String getUsrName(String id) {
    	
    	String result = this.jdbcTemplate.queryForObject("select name from test where id=?", String.class, id);
        return result;
    }
    
    @Operation(summary="사용자를 등록한다.", description="파라미터 id 필수, name필수")
    @PostMapping("/usr/id")
    public int setUsrId(String id, String name) {

        int result = this.jdbcTemplate.update("insert into test(id, name) values(?,?)",id,name);
        return result;
    }
    
    @Operation(summary="사용자를 수정한다.", description="파라미터 id 필수, name필수")
    @PutMapping("/usr/id")
    public int updateUsr(User user) {

        int result = this.jdbcTemplate.update("udpate test set name=? where id=?",user.name,user.id);
        return result;
    }
}

user.java

package com.myproject.firstproject;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.Setter;
@AllArgsConstructor
@Getter
@Setter
@Schema(description = "유저")
public class User {

	    @Schema(description = "아이디", defaultValue = "testId")
	    public String id;
	    @Schema(description = "이름", defaultValue = "testName")
	    public String name;

}

서버 기동후 http://localhost:8080/swagger-ui/index.html 로 접속했을때 다음과 같이 페이지가 출력되면 정상적으로 적용된 것입니다.