[Utils] 마크다운 API 명세 템플릿

가능하다면 gitbook이나 swagger같은 공유 가능한 API 명세서를 쓰는 것이 제일 좋겠지만, 그렇지 못할 때는 markdown이라도 써서 API를 명세해야 합니다. 개인적으로 gitbook의 명세가 상당히 마음에 들어서 비슷하게 템플릿을 만들어 봤습니다.

 

적용한 모습은 다음 페이지에서 참고하면 됩니다.

 

https://github.com/osamhack2022/APP_Meerkat_IQDan/wiki/API-Specification

 

코드는 아래와 같습니다.

# 일반 API 명세

![](https://img.shields.io/static/v1?label=&message=GET&color=blue)
![](https://img.shields.io/static/v1?label=&message=POST&color=brightgreen)
![](https://img.shields.io/static/v1?label=&message=PUT&color=orange)
![](https://img.shields.io/static/v1?label=&message=DELETE&color=red)
![](https://img.shields.io/static/v1?label=&message=EMIT&color=brightgreen)
![](https://img.shields.io/static/v1?label=&message=ON&color=blue) 

### API Description

> ![](https://img.shields.io/static/v1?label=&message=GET&color=blue) <br>
> code.seholee.com:8082/**example**

<details markdown="1">
<summary>Operational Summary</summary>

Operational description

#### Parameters

##### Path

| name | type | description | required |
| :---: | :---: | :---: | :---: |
| id | type | parameter description(optional) | Optional or Required |

##### Headers

| name | type | description | required |
| :---: | :---: | :---: | :---: |
| id | type | parameter description(optional) | Optional or Required |

##### Cookies

| name | type | description | required |
| :---: | :---: | :---: | :---: |
| id | type | parameter description(optional) | Optional or Required |

##### Body

| name | type | description | required |
| :---: | :---: | :---: | :---: |
| id | type | parameter description(optional) | Optional or Required |

#### Response

  <details markdown="1">
  <summary>200 OK : description</summary>

  ```
  {
    // Response
  }
  ```
  </details>

  <details markdown="1">
  <summary>201 Created: description</summary>

  ```
  {
    // Response
  }
  ```
  </details>

</details>
<br>






### 예제: 로그인

> ![](https://img.shields.io/static/v1?label=&message=POST&color=brightgreen) <br>
> code.seholee.com:8082/**auth/login**

<details markdown="1">
<summary>detail</summary>

#### Parameters

##### Body

| name | type | description | required |
| :---: | :---: | :---: | :---: |
| uid | string | 로그인 할 사용자의 아이디 | **Required** |
| password | string | 로그인 할 사용자의 비밀번호 | **Required** |

#### Response

  <details markdown="1">
  <summary>200 Ok : 성공적으로 로그인 된 경우</summary>
  
  ```
  {
    "data" : {
      "expiresIn": 3600,
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTEs..."
    },
    "message" : "login"
  }
  ```
  </details>

이외의 에러코드 작성 바람
</details>
<br>






# Socket Event Specification

## Authentication

token 문제로 연결되지 않는 경우 connect_error를 전송.

-   invalid token인 경우 Wrong authentication token
-   token이 없는 경우 Authentication token missing

socket event는 [발송자]:[이벤트 명] 형식으로 만듭니다.

## Server-side

### Initial Connection

<details markdown="1">
<summary>detail</summary>

#### Connect Option

| namespace | path | transports | reconnectionAttempts | auth |
| :---: | :---: | :---: | :---: | :---: |
| /chat | /socket.io | ['websocket'] | 2 | {token: [사용자 토큰]} |


  <details markdown="1">
  <summary>example</summary>

  ```
    io(env.prod.apiBaseUrl + '/chat', {
      path: '/socket.io',
      transports: ['websocket'],
      reconnectionAttempts: 2,
      auth: { token: userToken },
    });
  ```
  </details>

</details>
<br>






### API Description

> ![](https://img.shields.io/static/v1?label=&message=EMIT&color=brightgreen)  <br>
> [SENDER]:[EVENTNAME]

<details markdown="1">
<summary>Operational Summary</summary>

Operational description

#### Message Object

| name | type | description | required |
| :---: | :---: | :---: | :---: |
| attribute name | type of attribute | Attribute description(optional) | Optional or Required |


  <details markdown="1">
  <summary>example</summary>

  ```
    // example
  ```
  </details>

</details>
<br>






### 예제: 속해있는 모든 채팅방 소켓 room들에 접속 요청

> ![](https://img.shields.io/static/v1?label=&message=EMIT&color=brightgreen)  
> client:joinAllChatrooms

<details markdown="1">
<summary>detail</summary>

해당 사용자가 속해있는 모든 room에 접속 요청을 보냄.

#### Message Object

| name | type | description | required |
| :---: | :---: | :---: | :---: |
| chatroomIds | integer | 사용자가 속해있는 room id 리스트 | Required |


  <details markdown="1">
  <summary>example</summary>

  ```
    socket.emit("client:joinAllChatrooms", [1, 2]);
  ```
  </details>
<br>