테스트코드를 통해 생성하는 swagger ui입니다. restdocs의 형식으로 작성하여 snippets 폴더 내에 resource.json을 생성하고, 이를 통해 openapi-3.0.1.json을 생성하여 swagger-ui를 만들어냅니다.
기본 설정을 마치고 CityControllerTest에 완벽적용하였습니다. UserControllerTest의 회원가입에도 적용해보았습니다. PR이 길어질거 같아 회원가입까지만 구현하여 올렸습니다.
이런식으로 UI가 나타나고, local 환경 확인 시 Servers 드롭다운을 변경하여 localhost:8080으로 변경시 api 호출도 정상 가능합니다.
POST 쪽도 만들어봐야할 거 같아서 만든 Join입니다. 이런 식으로 값 설정가능합니다.
Schema에 Validation 정보도 자동으로 넣을려고했으나 실패하여 description으로 적었습니다. 자세한 내용은 커밋 설명에 적혀있습니다.
api 문서를 작성하며 사용하게 되는 라이브러리의 data class ResourceSnippetParameters입니다.
data class ResourceSnippetParameters @JvmOverloads constructor(
val summary: String? = null,
val description: String? = null,
val privateResource: Boolean = false,
val deprecated: Boolean = false,
val requestSchema: Schema? = null,
val responseSchema: Schema? = null,
val requestFields: List<FieldDescriptor> = emptyList(),
val responseFields: List<FieldDescriptor> = emptyList(),
val links: List<LinkDescriptor> = emptyList(),
val pathParameters: List<ParameterDescriptorWithType> = emptyList(),
val queryParameters: List<ParameterDescriptorWithType> = emptyList(),
val formParameters: List<ParameterDescriptorWithType> = emptyList(),
val requestHeaders: List<HeaderDescriptorWithType> = emptyList(),
val responseHeaders: List<HeaderDescriptorWithType> = emptyList(),
val tags: Set<String> = emptySet()
)
위 정보를 집어넣어 각 api에 대해 정보를 표기할 수 있습니다. 상세 방법은 이미 구현된 api 문서 코드를 참고하면 될 거 같습니다.
Summary
86에서 언급한대로 restdocs api spec을 적용하였습니다.
Description
테스트코드를 통해 생성하는 swagger ui입니다. restdocs의 형식으로 작성하여 snippets 폴더 내에 resource.json을 생성하고, 이를 통해 openapi-3.0.1.json을 생성하여 swagger-ui를 만들어냅니다.
기본 설정을 마치고 CityControllerTest에 완벽적용하였습니다. UserControllerTest의 회원가입에도 적용해보았습니다. PR이 길어질거 같아 회원가입까지만 구현하여 올렸습니다.
이런식으로 UI가 나타나고, local 환경 확인 시 Servers 드롭다운을 변경하여 localhost:8080으로 변경시 api 호출도 정상 가능합니다.
POST 쪽도 만들어봐야할 거 같아서 만든 Join입니다. 이런 식으로 값 설정가능합니다.
Schema에 Validation 정보도 자동으로 넣을려고했으나 실패하여 description으로 적었습니다. 자세한 내용은 커밋 설명에 적혀있습니다.
api 문서를 작성하며 사용하게 되는 라이브러리의 data class ResourceSnippetParameters입니다.
위 정보를 집어넣어 각 api에 대해 정보를 표기할 수 있습니다. 상세 방법은 이미 구현된 api 문서 코드를 참고하면 될 거 같습니다.
api 문서 접속의 경우
/docs/swagger-ui/index.html로 가능합니다. 즉, 로컬 환경에서는 http://localhost:8080/docs/swagger-ui/index.html로 접속하면 됩니다.resources/static/docs 폴더 내부에 json 파일이 생성되어야 실행이 됩니다. 이는 gradle task인 openapi3를 실행하면 자동으로 생성되게 됩니다.
intelliJ에서는 gradle의 openapi3를 실행함으로써 바로 만들 수 있습니다. json 파일이 생성되면 Serverapplication 실행 시 위에서 언급한 url(
/docs/swagger-ui/index.html)로 접속이 가능해집니다.이제부터 생성하는 통합 테스트는 같은 형식으로 api 문서화를 함께하며 진행하면 될거 같습니다!
Related Issue
Issue Number: close #86