[ API ] 프로젝트 API 문서화 DEVLOG

 

# Reference

 

LINE Engineering - 문서 엔지니어링과 API 문서화 by 전정은

https://engineering.linecorp.com/ko/blog/document-engineering-api-documentation/

문서 엔지니어링과 API 문서화 - LINE ENGINEERING

 

API 레퍼런스 문서 제작 트렌드 및 도구 조사 by 지단로보트

https://jsonobject.tistory.com/355

API 레퍼런스 문서 제작 트렌드 및 도구 조사

 

백엔드가 이정도는 해줘야 함 - 6.API 스펙 설계와 문서화 방식 결정 - (2) by city7310

https://velog.io/@city7310/%EB%B0%B1%EC%97%94%EB%93%9C%EA%B0%80-%EC%9D%B4%EC%A0%95%EB%8F%84%EB%8A%94-%ED%95%B4%EC%A4%98%EC%95%BC-%ED%95%A8-6.-API-%EC%8A%A4%ED%8E%99-%EC%84%A4%EA%B3%84%EC%99%80-%EB%AC%B8%EC%84%9C%ED%99%94-%EB%B0%A9%EC%8B%9D-%EA%B2%B0%EC%A0%95-2

 

 Restful API 문서 작성 by Peter Kim

https://medium.com/empo-kr/api-%EB%AC%B8%EC%84%9C%EB%A5%BC-%EC%A0%9C%EB%8C%80%EB%A1%9C-%EC%9E%91%EC%84%B1%ED%95%B4%EB%B3%B4%EC%9E%90-feat-insomnia-2a44ee4f0b75

API 문서를 제대로 작성해보자 (feat. insomnia)

 

TISTORY OpenAPI

https://tistory.github.io/document-tistory-apis/apis/

소개 · GitBook

 

0) 학습개요

 

아대밀맵 서비스가 진짜 얼마 남지 않아 Backend API의 정리가 필요한 시점이 되었습니다.

(사실 이미 해놨어야 하지만 너무 바빠서 미뤄뒀음)

이전까지는 Backend API 문서를 다른 팀원이 작성하거나 그래픽으로 정리해서 줘본 경험밖에 없어서, 이번 기회에 Swagger를 이용하여 일반에 바로 공개할 수 있는 API를 만들어보고자 하였습니다.

 

1) API 문서화도구 선정

API 레퍼런스를 생성하기 위한 도구는 여러가지가 존재합니다.

 

-------

 

1) Slate

마크다운 기반 문서포멧 및 반응형 렌더러 제공.

문서 포맷이 직관적이며 단순.

1개 테마 / 3개 패널 디자인

 

학습난이도 낮음 | 결과물 세련됨 (최소 노력 최대 결과)

 

2) API Blueprint

Slate와 유사.

문서 표현가능범위 다양.

렌더러 없음 (Third-party 렌더러 사용이 필요함 (ex: Aglio))

 

+) Aglio: 5개 테마 / 2, 3패널 디자인 제공

 

학습난이도 약간 높음 (< Slate)

 

3) Swagger

가장 유명

JSON & RAML 기반 문서포맷 제공

강력한 REST API 설계철학 강제 => 비준수 서비스: 적용불가

자체 렌더러 존재 (Swagger UI), 유명한 Third-party 렌더러 존재 (ReDoc, 3패널 디자인)

 

4) GitBook

깔끔한 UI 제공

Git의 commit / merge가 존재 -> 문서 버전 관리 가능 (=업데이트 내역 확인 용이)

테스트 요청 / 응답 사용 불가

팀이 사용할 경우 유료 (개인은 무료)

 

-------

 

저는 이중 GitBook을 사용했고, 이유는 다음과 같습니다.

 

1) API로 공개하는 정보를 사용할 대상이 제한적임 (아주대학교 내에서 인근 음식점 정보를 활용한 개발 프로젝트를 진행하고자 하는 학우)

2) 테스트 요청을 지원해야하는 필요성이 크지 않음 (1과 상동)

3) 개인 프로젝트이므로 API 문서 작성이 무료

 

 

 

2) Gitbook 둘러보기

 

GitBook에 가입하고 난 뒤 API Docs를 선택 후 진행했습니다.

 

 

API문서 생성이 완료되었습니다. 양이 많아 한번에 작성하진 못했고, user api만 업로드 했습니다.

지속적으로 업데이트 하며 서비스 공개 직후 공개 할 예정입니다.

 

https://nate-crema.gitbook.io/aj-mealmap-api/

Introduction - AJ Mealmap API

 

--------|Updated

 

2021.11.13 | 문서 신규생성