API 문서화

1. by 홍석주 2022.07.26
API 문서화

2. OAS란?
OpenAPI Speci
fi
cation
RESTful 웹서비스를 약속된 규칙에 맞게 API 스펙을 json과 yaml 형식으로 표현
이를 통해, 직접 소스코드를 보거나 추가 문서 필요없이 서비스를 이해할 수 있다.

3. API 문서화를 잘 해야하는 이유?
프론트와 백엔드간 업무 효율화를 위해!
아~! 내가 이렇게 요청 보내면
이렇게 응답이 오는구나!!

4. Swagger? Rest Docs?
뭐를 쓰는것이 좋을까?
Rest Docs Swagger
장점
프로덕션 코드에 영향이 없다. 문서상에 API를 테스트할 수 있는 기능이 있다.
테스트 코드가 성공해야 문서 작성이 가능하다. 테스트 코드 필요없어 적용이 편리하다.
단점
테스트 코드가 성공해야 하므로 불편
프로덕션 코드에 테스트와 관련된 어노테이션 추가
라이브러리가 바뀌는 경우 사용 불편
테스트 코드를 잘 짜줘야 한다. 프로덕션 코드에 적용되기에 코드가 지저분해짐
일단 둘 다 써보자!

5. Swagger 부터
라이브러리 추가
implementation 'io.springfox:springfox-boot-starter:3.0.0'
이전에는 아래와 같이 두개의 라이브러리를 입력했는데, 지금은 위와 같이 하나만 넣어
주면 전부 추가됨
compile('io.springfox:springfox-swagger2:2.9.2')
compile('io.springfox:springfox-swagger-ui:2.9.2')

6. Swagger 부터
라이브러리 추가
implementation 'io.springfox:springfox-boot-starter:3.0.0'
이전에는 아래와 같이 두개의 라이브러리를 입력했는데, 지금은 위와 같이 하나만 넣어
주면 전부 추가됨
compile('io.springfox:springfox-swagger2:2.9.2')
compile('io.springfox:springfox-swagger-ui:2.9.2')

7. Swagger 부터
Con
fi
guration 추가
@Configuration
public class SwaggerConfig {
@Bean
public Docket swaggerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.consumes(getConsumeContentTypes())
.produces(getProduceContentTypes())
.apiInfo(swaggerInfo()).select()
.apis(RequestHandlerSelectors.basePackage("me.somefood.swaggertest.con
troller"))
.paths(PathSelectors.any())
.build()
.useDefaultResponseMessages(false);
}
}

8. Swagger 부터
컨트롤러 추가
@RequiredArgsConstructor
@RequestMapping("/api/v1/posts")
@RestController
public class PostController {
private final PostService postService;
@ApiOperation(value="포스트 전체 갖고오기", notes="포스트 전체 갖고오기 노트")
@ApiResponses({
@ApiResponse(code = 200, message = "API 정상 작동"),
@ApiResponse(code = 500, message = "서버 에러")
})
@GetMapping
public List<Post> allPosts() {
return postService.findAllPost();
}

9. Swagger 부터
http://localhost:8080/swagger-ui/ 에 접속
접속하면 다음과 같이 컨트롤러의 명세와 모델들을 확인할 수 있다!

10. RestDocs
라이브러리 추가
// asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor'
asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
task copyDocument(type: Copy) {
dependsOn asciidoctor
from file("build/docs/asciidoc/")
into file("src/main/resources/static/docs")
}

11. RestDocs
테스트
@Test
void findAll() throws Exception {
List<PostResponse> postResponses = Lists.newArrayList(
new PostResponse(1L, "title1", "content1"),
new PostResponse(2L, "title2", "content2")
);
when(postService.findAll()).thenReturn(postResponses);
this.mockMvc.perform(get("/posts")
.accept(MediaType.APPLICATION_JSON)) // 1
.andExpect(status().isOk())
.andDo(document("post-get-all",
responseFields( // 2
fieldWithPath("[].id").description("Post Id"), // 3
fieldWithPath("[].title").description("Post 제목"),
fieldWithPath("[].content").description("Post 내용")
)
));
}

12. RestDocs
asciidoc 작성

13. RestDocs
gradle 빌드 후 static에 rest.html이 생기면 접속해서 확인 가능

14. 둘다 써보며 느낀점
Swagger RestDocs
• 입문하기가 비교적 쉬운 듯.
• 대신 그만큼 지저분해진다.
• 코드가 지저분해지지 않음
• Mock 테스트에 대한 충분한
이해도와 asciidoc 작성법 공부 필요