[SpringBoot] Springdoc을 이용한 swagger, API DOCS

엄청 오래전엔 javadoc 으로 Export 해서 문서로 봤거나 

직접 api 문서를 작성해서 전달하거나 했었던 시절이 있었다.

 

지금 당장은 api docs 가 필요하진 않은데 프로젝트 말미에 api 연동부 문서들이 필요해질 것 같아

미리 학습겸 셋팅해보려고 한다.

 

Springdoc 이랑 Spring Rest Docs 둘중에 뭘로 할까 하다가

각자의 장단점이 있고 Spring Rest Docs 가 더 이점이 있어보이긴 했으나,

지금 당장 필요한 단계가 아니기 때문에 (사실 테스트모듈도 없음)

swagger를 사용해서 간단히 보여주고 셋팅 해보려고 한다.

 

 

gradle 설정.

implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'

 

application 설정.

springdoc:
  swagger-ui:
    path: /api-docs.html
  api-docs:
    path: /api-docs
  show-actuator: true
  default-produces-media-type: application/json

 

대충 이렇게 간단하게 해놓고 어떻게 나오나 확인!

 

 

 

localhost/api-docs.html

 

 

localhost/api-docs

 

 

 

기본 swagger-ui 화면이 생성된 것을 확인 할 수 있다.

controller를 아직 생성하지 않아서 아무 내용이 없다.

 

 

작성한 API 가 어떻게 나오는지 확인하기 위해 아래와 같이 controller 를 간단히 작성해서 swagger를 확인해보면,

 

@Tag(name="API", description = "Sample API 입니다.")
@RestController
@RequestMapping("/api")
public class SampleController {

	@Autowired private SampleService sampleService;
	
	@PostMapping("/getUser/{age}")
	public List<User> getUser(@Parameter(description = "나이") @PathVariable("age") int age) {
		return sampleService.getUser(age);
	}
}

 

작성한 API 리스트

 

 

작성한 API 정보

 

 

API 테스트 및 결과 확인

 

 

단점이라면 API 정보 작성을 위해 코드에 어노테이션을 무지하게 나열해야 한다는 점.

간단하고 빠르게 api docs 를 작성해봤습니다.

 

 

 

 

 

 

 

 

 

---

https://springdoc.org/

OpenAPI 3 Library for spring-boot