외부 API로 문서 작성하기 4.0

외부 API로 문서 작성하기 4.0

쓰리래빗츠 북에서 외부 API를 호출해서 문서를 작성하는 방법을 설명합니다.

1외부 API 만들기

1.1외부 API 설정

다음 순서로 외부 API를 설정합니다.

1

<도구 | 외부 시스템> 메뉴로 이동합니다.

관리 권한이 있는 사용자만 접근할 수 있습니다.

2

<1API 만들기> 링크를 클릭합니다.

3

내용을 입력한 후 저장합니다.

표 1외부 API 정보

내용

설명

필수 여부

시스템 아이디

내용을 업데이트할 때 사용하는 임의의 구분자로 고유해야 합니다. 만든 후에 변경할 수 없습니다.

예

이름

구분을 위해 임의로 부여하는 외부 API 이름입니다.

예

API 아이템 URL

외부 API로 만들 수 있는 아이템 목록을 반환하는 URL입니다.

예

API 단락 URL

아이템에 해당하는 단락을 반환하는 URL입니다.

예

4

외부 API 테스트

<2테스트> 링크를 클릭합니다.

연결에 성공하면 아이템 목록이 보입니다.

1.2접근 권한 설정

다음 순서로 특정 API에 접근할 수 있는 사용자 또는 그룹을 설정합니다.

<1접근 권한 변경> 링크를 클릭합니다.

그룹 또는 사용자를 선택한 후 <저장> 버튼을 클릭합니다.

글 쓰기 권한이 있는 사용자만 목록에 나타납니다.

1.3외부 API 삭제

외부 API를 삭제하려면 <1삭제> 링크를 클릭합니다.

삭제한 것과 같은 시스템 아이디로 외부 API를 만들면 이전에 가져오기 한 단락을 다시 동기화할 수 있습니다.

2외부 API로 문서 만들기

먼저 문서를 만듭니다. 문서를 만드는 자세한 방법은 쓰리래빗츠 북 사용자 가이드를 참고합니다.

<대시보드> 메뉴에서 <책 만들기>를 선택합니다.

내용을 입력한 후 저장합니다.

차례 패널에서 <장 만들기> 링크를 클릭합니다.

내용을 입력한 후 저장합니다.

장의 <내용 편집> 링크를 클릭해서 에디터를 엽니다.

외부 API를 호출하는 방법입니다.

에디터 오른쪽 위에 있는 <1외부 시스템> 버튼을 클릭합니다.

2외부 API 이름을 선택합니다. 접근 권한이 있는 외부 API만 보입니다.

접근 권한을 설정하는 방법은 접근 권한 설정을 참고합니다.

아이템을 선택한 후 <3가져오기> 버튼을 클릭합니다.

선택한 단락이 있다면 선택한 단락 아래에, 없다면 맨 아래에 가져오기한 단락을 추가합니다.

단락에 시스템 아이디와 아이템 아이디와 단락 아이디 라벨이 붙습니다. 업데이트할 때 사용합니다.

외부 API로 가져오기와 관련해서 다음을 참고합니다.

쓰리래빗츠 북 에디터의 다른 기능을 모두 사용할 수 있습니다. 예를 들어 다른 단락으로 자세한 설명을 추가할 수 있습니다.

외부 API로 내용을 업데이트를 한다면 외부 API로 가져온 단락은 쓰리래빗츠 북에서 직접 수정하지 않습니다.

3외부 API 업데이트

외부 API가 반환하는 내용이 바뀌었다면 그 내용을 업데이트할 수 있습니다.

에디터를 엽니다.

에디터 오른쪽 위에 있는 <1외부 시스템> 버튼을 클릭합니다.

<2외부 시스템 단락 업데이트> 버튼을 클릭합니다.

업데이트와 관련해서 다음을 참고합니다.

이력 비교로 변경 내역을 확인할 수 있습니다.

접근 권한이 없는 외부 API는 업데이트하지 않습니다.

더 이상 존재하지 않는 단락을 자동으로 삭제하지 않습니다. 직접 해당 단락을 삭제 합니다.

새로운 단락은 추가하지 않습니다.

단락 순서 변화는 업데이트하지 않습니다.

쓰리래빗츠 북에서 수정한 단락 옵션이 외부 API의 단락 옵션으로 바뀝니다.

4URL 구현

외부 API를 호출할 때 추가적인 인증을 지원하지 않습니다. URL 리다이렉션도 지원하지 않습니다.

4.1API 아이템 URL

외부 API로 가져오기할 아이템을 정의합니다. JSON 형식입니다.

{
  "items": [
    {
      "id": "i_01",
      "name": "아이템 01"
    },
    {
      "id": "i_02",
      "name": "아이템 02"
    },
    {
      "id": "i_03",
      "name": "아이템 03"
    }
  ]
}

items 속성으로 여러 아이템을 JSON 배열로 정의합니다. 하나의 아이템은 id와 name 속성을 가진 JSON 객체입니다.

표 2아이템(item) 객체

속성

설명

유형

필수

id

하나의 외부 API에서 id 값이 유일해야 합니다. 쓰리래빗츠 북에서 중복 체크를 하지는 않습니다.

문자

예

name

아이템 이름

문자

예

4.2API 단락 URL

선택한 아이템에 해당하는 단락을 반환합니다. 하나 이상의 단락을 반환할 수 있습니다. JSON 형식입니다.

GET 방식 쿼리 문자열로 아이템 아이디 값을 전달합니다. 예를 들어 API 아이템 URL이 http://127.0.0.1:8090/get_elements이고 아이템 아이디가 i_01이라면 다음 주소를 호출합니다.

http://127.0.0.1:8090/get_elements?item=i_01

{
  "elements": [
    {
      "id": "u_01",
      "type": "heading1",
      "content": "서버 아이디",
      "option": {
        "sectionView": "tab"
      }
    },
    {
      "id": "u_02",
      "type": "normal",
      "content": "서버 아이디는 <strong>총 36자의 문자열</strong>입니다."
    }
  ]
}

elements 속성으로 여러 단락을 JSON 배열로 정의합니다. 하나의 단락은 id와 type, content, option 속성을 가진 JSON 객체입니다.

표 3단락(element) 객체

속성

설명

유형

필수

id

URL 응답에서 id 값이 유일해야 합니다. 쓰리래빗츠 북에서 중복 체크를 하지는 않습니다.

문자

예

type

단락 유형

문자

예

content

단락 내용

문자

자동 페이지 나누기, 빈 페이지, 여백, 수평선을 제외한 단락 유형은 필수

option

옵션

객체

4.2.1type 속성

type 속성으로 단락 유형을 설정합니다. 다음 값을 입력할 수 있습니다.

단락 유형

갑

보통

normal

제목 1

heading1

제목 2

heading2

제목 3

heading3

제목 4

heading4

제목 5

heading5

헤드라인

headline

코드

code

명령어

command

줄 바꿈 유지

pre

블럭 인용구

blockquote

권두 명구

epigraph

순서 목록

ordered_list

비순서 목록

unordered_list

정의 목록

definition_list

콜아웃 목록

callout_list

단계

step1

노트

note

팁

tip

주의

caution

표 단락

table

자동 페이지 나누기

page_break

빈 페이지

blank_page

여백

space

수평선

horizontal_line

다음 단락 유형은 외부 API로 만들기를 지원하지 않습니다.

단락 유형

갑

교정

proofreading

그림 단락

image

차례

toc

그림 차례

list_of_figures

표 차례

list_of_tables

코드 차례

list_of_codes

용어집

glossary

약어집

abbreviation

찾아보기

index

레이아웃 페이지

layout_page

디자인 페이지

single_design_page

다른 단락 포함하기

include

4.2.2content 속성

JSON이 정한 형식에 맞게 문자를 작성해야 합니다. 예를 들어 "은 탈출문자(\)를 붙여 \"로 작성합니다.

4.2.2.1텍스트 단락

순서 목록과 같이 줄 바꿈이 필요한 단락은 줄 바꿈(\n) 글자로 줄 바꿈합니다.

* 사과\n* 배\n* 포도

태그가 아닌 <과 >과 & 문자는 &lt;와 &gt;와 &amp;로 처리합니다.

태그가 아닌 &lt;과 &gt;과 &amp; 문자는 &amp;lt;와 &amp;gt;와 &amp;amp;로 처리합니다.

4.2.2.1.1문자 유형

문자 유형은 html 태그로 처리합니다.

리눅스 배포판과 버전에 따라 <strong>자바를 설치하는 방법</strong>이 매우 상이합니다. 그래서 자바 설치는 리눅스 배포판과 버전에 맞게 진행합니다.

문자 유형별 html 태그는 다음과 같습니다.

문자 유형

태그

매우 강조

strong

강조

em

코드

code

키보드

kbd

인라인 주석

small

아래 첨자

sub

위 첨자

sup

삭제

del

모든 태그는 소문자로 작성합니다.

콜아웃 단락 유형은 다음과 같이 작성합니다.

&lt;<span class=\"callout\">1</span> 비밀번호를 잊으셨나요?&gt; 링크는 메일 서버를 설정해야 나타납니다.

4.2.2.1.2링크

웹 링크는 class 속성 값을 link로 하는 a 태그로 작성합니다.

쓰리래빗츠 북을 설치하는 방법은 <a class=\"link\" href=\"installation_guide_3_0_ko\">쓰리래빗츠 설치 가이드</a>를 참고합니다.

메일 링크는 class 속성 값을 link로 하는 a 태그로 작성합니다. href 속성 값이 메일 형식을 지켜야 합니다.

이메일: <a class=\"link\" href=\"mailto:support@3rabbitz.com\">support@3rabbitz.com</a>

4.2.2.1.3마크

찾아보기를 위한 마크는 다음과 같이 작성합니다. span 태그 내용 작성 방법은 다음을 참고합니다.

본문<span class=\"mark index\">본문</span>

4.2.2.1.4주석

주석은 다음과 같이 `<cite><span>`과 </span></cite> 사이에 작성합니다.

대부분의 입력 화면에서 Enter<cite><span>맥 OS에서는 RETURN 키</span></cite> 키를 누르면 저장합니다.

4.2.2.1.5단락 안 그림

웹에서 가져오기한 단락 안 그림은 img 태그 src 속성에 그림 URL을 입력합니다. width와 height 속성도 설정해야 합니다.

서식 지우기(<img src=\"https://www.3rabbitz.com/resource/image/book/editor/clear_format.png\" width=\"16\" height=\"16\" />)를 클릭합니다.

4.2.2.2표 단락

표 단락은 type 속성은 table이고 content 속성에 HTML table 태그로 내용을 작성합니다. table 태그 구조는 다음과 같습니다.

<table>
  <caption>주요 서식</caption>
  <thead>
    <tr>
      <th><div>항목</div></th>
      <th><div>설명</div></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th><div>강조</div></th>
      <td><div>강조가 필요한 단어 및 문장은 진하게 표기</div></td>
    </tr>
    <tr>
      <th><div>코드, 파일 이름</div></th>
      <td><div>코드, 명령어, 파일 이름 등은 고정폭 글꼴로 표기</div></td>
    </tr>
  </tbody>
</table>

이 예제에서는 읽기 편하게 하기 위해서 태그와 태그 사이에 줄 바꿈이나 들여쓰기를 했지만 실제로는 줄 바꿈이나 여백이 있어서는 안됩니다. 셀 내용은 텍스트 단락과 작성 방법이 같습니다.

표 제목은 caption 태그에 작성합니다. 표 제목이 없을 때도 <caption></caption>으로 설정해야 합니다.

머리 행은 thead 태그 안에 작성합니다.

일반 행은 tbody 태그 안에 작성합니다.

바닥 행은 tfoot 태그 안에 작성합니다.

thead와 tfoot 태그 안에서는 td 태그가 아닌 th 태그를 사용합니다.

tbody 태그 안에서 제목 셀은 th 태그로 작성합니다.

td와 th 태그 아래에 div 태그를 작성하고 그 안에 셀 내용을 작성합니다.

td와 th 태그의 colspan과 rowspan 속성으로 셀을 병합할 수 있습니다.

<td colspan=\"2\" rowspan=\"3\"><div>...</div></td>

td와 th 태그의 class 속성에 셀 정렬 방법을 설정할 수 있습니다.

정렬

class 값

텍스트 왼쪽 맞춤

to_left

텍스트 오른쪽 맞춤

to_right

텍스트 가운데 맞춤

to_center

텍스트 양쪽 맞춤

to_justify

텍스트 위에 맞춤

to_top

텍스트 아래에 맞춤

to_bottom

텍스트 중간에 맞춤

to_middle

코드 셀이라면 td와 th 태그의 class 속성에 code_cell을 지정합니다.

<td class=\"code_cell\"><div>...</div></td>

4.2.2.3객체 단락

객체 단락은 content 속성 없이 type 속성 만을 설정합니다. 다음은 수평선 객체 단락입니다.

{
  "id": "u_06",
  "type": "horizontal_line"
}

4.2.3option 객체

단락 별 옵션을 설정합니다. 예를 들어 PDF에서 단락을 감추려면 exportExclude 속성으로 설정하고 제목 1 단락의 절 모습을 tab으로 하려면 sectionView 속성으로 설정합니다.

{
  "id": "u_01",
  "type": "heading1",
  "content": "서버 아이디",
  "option": {
    "exportExclude": "pdf",
    "sectionView": "tab"
  }
}

다음 옵션이 있습니다.

표 4option 객체 속성

옵션

설명

적용 단락

기본 값

alias

사용자 정의 아이디. 쓰리래빗츠 북의 한 문서 안에서 중복이 없어야 합니다. 가져오기할 때 쓰리래빗츠 북에서 중복 체크를 하지는 않습니다.

전체

codeLanguage

프로그래밍 언어. XML, HTML, CSS, JAVASCRIPT, JSON, JSP, C, C++, C#, OBJECTIVE_C, RUBY, PYTHON, SQL 등으로 설정합니다.

코드

표

codeNumbering

번호 매기기

코드

true

exportExclude

단락 감추기. 웹 뷰어에서 숨기려면 web으로, PDF에서 숨기려면 pdf로 설정합니다. 모두 숨기려면 쉼표를 구분자로 web,pdf로 설정합니다.

전체

ignoreStepIndent

단계 단락 들여쓰기 무시하기

보통

헤드라인

코드

명령어

노트

팁

주의

표

false

renumbered

번호 새로 매기기. true 또는 false로 설정합니다.

순서 목록

단계

false

sectionView

절 모습. accordion 또는 tab으로 설정합니다.

제목 1

tableLayout

표 레이아웃. fixed 또는 auto로 설정하거나 임의의 값을 지정합니다. 사용자 가이드를 참고합니다.

표

fixed