이런 느낌



샘플

소개

이 기사에서 소개하고 있는 순서는 아래의 참고 사이트와 완전히 같습니다.

Swagger 정의 파일에서 적당한 느낌의 정적 REST API 문서 만들기 - Witch on the Other Shore

최근에는 Swagger라든지 API 정의 써 Swagger UI를 어떻게 호스팅하고 배포하는 것 같은 느낌의 개발도 보통이 되어 왔지만, 아직 정적 파일로 API 문서가 필요하다는 경우도 상당히 있다고 생각한다.

일단 swagger-codegen에서 html을 출력할 수도 있지만 겸손하게 말해 외형이 어색하기 때문에, 지금까지는 Swagger UI의 화면을 브라우저에서 열어 PDF로 출력하는 것 같은 방법으로 비교적 무리하게 문서를 생성해 했다. (귀찮아서 당연히 유지 보수하지 않습니다)

일부러 스스로 툴 만드는 것도 귀찮아서, 뭔가 좋은 방법 없을까라고 생각해 조사하면 최초로 써 있는 기사를 발견해, 그것이 비교적 좋은 느낌이었으므로 소개해 본다.

절차

처음에 소개한 기사와 함께 하고 있을 뿐.
각 툴의 빌드 방법이라든가 전 기사에는 실려 있지 않은 곳을 보충으로서 조금 추기.

사용하는 도구

swagger2markup-cli

Swagger -> AsciiDoc 변환

asciidoctor

AsciiDoc -> HTML 변환

해보자

1. swagger2markup-cli 빌드

$ git clone https://github.com/Swagger2Markup/swagger2markup-cli.git
$ cd swagger2markup-cli
$ gradle assemble

{PROJECT_ROOT}/build/libs에 swagger2markup-cli-{VERSION}.jar가 생성되면 OK

2. asciidoctor 설치

$ gem install --no-doc --no-ri asciidoctor

3. Swagger -> AsciiDoc 변환

우선 swagger 정의 파일을 AsciiDoc 형식으로 변환한다.
사용하는 것은 swagger2markup-cli

$ java -jar {swagger2markup-cli_ROOT}/build/swagger2markup-cli-{VERSION}.jar convert -i {SWAGGER_FILE_PATH} -f {OUTPUT_FILE_PATH}
ex) java -jar /usr/local/lib/swagger2markup-cli-1.3.2.jar convert -i swagger.yaml -f swagger
# カレントディレクトリに `swagger.adoc` が生成される

4. AsciiDoc -> HTML 변환

마지막으로 asciidoctor를 사용하여 AsciiDoc 형식의 파일을 HTML로 변환

$ asciidoctor -a toc=left {ASCII_DOC_FILE_PATH}
ex) asciidoctor -a toc=left swagger.adoc
# カレンドディレクトリに `swagger.html` が生成される

이상.
굉장히 간단! !

Docker 이미지 만든

간단하지만, 생성 할 때마다 Swagger -> AsciiDoc -> HTML로 단계를 밟는 것이 번거롭거나, 도구 빌드에 Gradle이나 Ruby가 필요하거나 조금 귀찮았기 때문에 문서 생성을 랩 한 Docker 이미지 만들기 했다.

ryutah/swagger document - Docker Hub

리포지토리의 문서에도 쓰여져 있는데 어떤 느낌으로 사용한다.

$ docker run \
    -v {SWAGGER_FILE_DIRECTRY}:{MOUNT_PATH} \
    ryutah/swagger-document {SWAGGER_FILE_PATH} {OUTPUT_FILE_PATH}

예) 현재 디렉토리의 sample.yaml를 sample.html로 문서 생성

$ docker run \
    -v $(pwd):/work \
    ryutah/swagger-document /work/sample.yaml /work/sample.html

1개의 HTML로서 출력할 수 있기 때문에 배포도 간단.

문서 출력하고 싶을 때라든가 CI에 짜넣고 싶을 때 어쩐지 사용할 수 있지 않을까.

참고 사이트

Swagger 정의 파일에서 거기 좋은 느낌의 정적 REST API 문서 만들기 - Witch on the Other Shore