250x250
Notice
Recent Posts
Recent Comments
Link
일 | 월 | 화 | 수 | 목 | 금 | 토 |
---|---|---|---|---|---|---|
1 | 2 | |||||
3 | 4 | 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | 14 | 15 | 16 |
17 | 18 | 19 | 20 | 21 | 22 | 23 |
24 | 25 | 26 | 27 | 28 | 29 | 30 |
Tags
- fastcampus
- 간단
- Zeppelin
- EMR
- spring
- SpringBoot
- hive
- vue
- java
- 자동
- Jenkins
- 레디스
- login
- Mac
- 클러스터
- Kafka
- Cluster
- config
- 예제
- 설정
- aws
- 머신러닝
- ec2
- Docker
- redash
- gradle
- 로그인
- 젠킨스
- Redis
- 자바
Archives
- Today
- Total
코알못
5분 안에 구축하는 APIDoc (API 규격서) 본문
728x90
apidoc 는 nodejs 로 만들어 졌으며 규격서를 자동으로 만들어주는 도구 이다.
nodejs 이기에 npm install로 설치가능하며 아래 공식 문서 참고하여 진행해본다.
apidoc 설치를 진행한다.
$ npm install apidoc -g
정상적으로 설치 되었는지 확인한다.
$ apidoc -v
_ _
__ _ _ __ (_) __| | ___ ___
/ _' | '_ \| |/ _' |/ _ \ / __|
| (_| | |_) | | (_| | (_) | (__
\__,_| .__/|_|\__,_|\___/ \___|
|_| v0.50.4
우선 apidoc 디렉토리를 만들고 그 안에서 진행해보자.
$ mkdir apidoc
$ cd apidoc
프로젝트 description 을 적으며 샘플 코드를 넣었다.
$ vi apidoc.json
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
구분 | 설명 |
name | 프로젝트의 이름 |
version | 프로젝트 버전 |
description | 프로젝트 소개 |
title | 브라우저 제목 텍스트 |
url |
API 경로(끝점)의 접두사 |
규격서 내용은 아래와 같이 샘플코드를 src 디렉토리에 만든다.
$ mkdir src
$ vi src/example.js
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
규격서 파일을 만들어 본다.
$ apidoc -i src -o apidoc
apidoc 파일이 생성되고 들어가서 보면 index.html 파일이 생성되어 있다.
$ cd apidoc
$ ls
assets index.html
html 파일을 브라우저에서 열면 아래와 같이 규격서 페이지가 정상적으로 만들어 진것을 볼 수 있다!
만드는 방법은 간단하고 심플하다.
저번시간에 [swagger를 이용해 규격서 생성] 해보았으며 두 도구를 비교해보면 아래와 같다.
구분 | apidoc | swagger |
처음 구축 난이도 | 낮다 | apidoc 보다 높다 |
운영 | API, 규격서 따로 운영 가능 | API 프로젝트에 같이 포함되어 있어 같이 규격서 반영됨 |
API 추가시 규격서 추가 공수 | swagger 보다 높다 (직접 API 명, 응답값을 기재 해야함) |
낮다 |
UI | 심플 | 다채로움 |
규격서 공유 | WEB, 문서로 공유 모두 가능 | 문서로 따로 공유 가능 |
위험성 | 규격서 공유를 문서로 하면 공유 받는 대상만 정보를 알수 있어 다소 위험성은 낮다. | 공유하는 규격서 사이트가 외부에 오픈 되어 있다면 아무나 규격서 페이지에 접근해서 볼 수 있어 정보 노출 위험이 있다. |
자원 사용도 | 낮다 | apidoc 보다 높다 |
어떤것이 더 좋다고 지정할 수 없으며 두 도구 모두 쉽게 규격서를 만들수 있다는것은 같다.
개발자와 API 특성, 운영 방법에 따라 맞는 도구를 선택하여 사용하면 될 것 같다.
끝!
728x90
'ETC' 카테고리의 다른 글
[Docker] 설치 (0) | 2022.03.25 |
---|---|
[Kubernetes & Docker] 무엇인가? (0) | 2022.03.25 |
내 도메인을 만들어보자! (0) | 2022.02.02 |
[mac] 사용중인 포트의 PID 찾기 (0) | 2021.12.24 |
[스프링부트] The temporary upload location [**/tmp/tomcat.*/work/Tomcat/localhost/ROOT]** is not valid (0) | 2021.09.27 |
Comments