Swagger의 YAML 파일은 Swagger Editor로 쓰는데 비주얼로 표시되어 행복하지만 위대한 사람들에게보고 할 때 "Swagger Editor 넣어주세요!"라고 말하기 어렵습니다.

그래서 @fanfanta의 Swagger 파일을 HTML로 변환을 참고로 Swagger의 YAML 파일을 HTML로 일발 변환하는 docker image를 만들었습니다.

편집 내역

0.2.0: swagger2markup의 속성을 사용자 정의할 수 있습니다.
0.3.0: 사이드바의 목차를 태그로 그룹화하도록 변경했습니다.

이용방법

Swagger의 YAML 파일이 있는 디렉토리에서 다음 명령을 실행하십시오.

docker run --rm --volume $(pwd):/mnt nmatsui/swagger2html swagger_filename.yaml

Swagger YAML 파일에서 생성된 AsciiDoc 형식의 파일과 HTML 파일이 같은 디렉터리에 생성됩니다.

swagger2markup 속성

이 Dockerfile이 이용하고 있는 swagger2markup 에는, 변환시의 거동을 제어하는 ​​프롭퍼티를 줄 수가 있습니다.
디폴트로 주는 프로퍼티는 이하가 됩니다만, Swagger 의 YAML 파일과 같은 디렉토리에 swagger2markup.properties 라는 이름으로 프로퍼티 파일을 만들어 두면, 그 프로퍼티 파일을 사용해 변환을 실시합니다.

swagger2markup.generatedExamplesEnabled=true
swagger2markup.tagOrderBy=AS_IS
swagger2markup.operationOrderBy=AS_IS
swagger2markup.definitionOrderBy=AS_IS
swagger2markup.parameterOrderBy=AS_IS
swagger2markup.propertyOrderBy=AS_IS
swagger2markup.responseOrderBy=AS_IS
swagger2markup.pathsGroupedBy=TAGS

구성 가능한 속성은 Swagger2Markup API Usage guide을 참조하십시오.

asciidoctor의 인수

swagger2markup이 생성한 AsciiDoc 형식의 문서를 asciidoctor을 사용하여 HTML화하고 있습니다. 다양한 CSS를 커스터마이즈 할 수도 있습니다만, 이번은 depth3까지의 목차를 내는 인수를 주고 있을 뿐입니다.

asciidoctor -a toc=left -a toclevels=3 swagger2markup_converted_file.adoc

Dockerfile

alpine Linux 3.7을 기반으로 Docker 이미지를 만들고 있습니다. 자세한 내용은 DockerHub 리포지토리nmatsui/swagger2html를 참조하십시오.

FROM alpine:3.7
MAINTAINER Nobuyuki Matsui <[email protected]>

RUN apk update && apk upgrade && \
    apk --no-cache add bash git openjdk8 ruby && \
    git clone https://github.com/Swagger2Markup/swagger2markup-cli.git /opt/swagger2markup-cli && \
    cd /opt/swagger2markup-cli && \
    ./gradlew jar && \
    mv /opt/swagger2markup-cli/build/libs/swagger2markup-*.jar /usr/local/lib/swagger2markup-cli.jar && \
    ./gradlew clean && \
    cd / && \
    rm -rf /root/.gradle && \
    rm -rf /opt/swagger2markup-cli && \
    gem install -N asciidoctor

WORKDIR /opt
RUN echo $'swagger2markup.generatedExamplesEnabled=true\n\
swagger2markup.tagOrderBy=AS_IS\n\
swagger2markup.operationOrderBy=AS_IS\n\
swagger2markup.definitionOrderBy=AS_IS\n\
swagger2markup.parameterOrderBy=AS_IS\n\
swagger2markup.propertyOrderBy=AS_IS\n\
swagger2markup.responseOrderBy=AS_IS\n\
swagger2markup.pathsGroupedBy=TAGS' > /opt/swagger2markup.properties
RUN echo $'#!/bin/sh \n\
if [ $# -ne 1 ]; then\n\
  echo "usage: docker run --volume \$(pwd):/mnt nmatsui/swagger2html swagger_filename.yaml"\n\
  exit 1\n\
fi\n\
YAML_FILE=$1\n\
BASE_NAME=${YAML_FILE%.*}\n\
if [ ! -e /mnt/${YAML_FILE} ]; then\n\
  echo "${YAML_FILE} not found"\n\
  exit 1\n\
fi\n\
PROPERTIES="/opt/swagger2markup.properties"\n\
if [ -e /mnt/swagger2markup.properties ]; then\n\
  echo "use custom properties"\n\
  PROPERTIES="/mnt/swagger2markup.properties"\n\
fi\n\
java -jar /usr/local/lib/swagger2markup-cli.jar convert -c ${PROPERTIES} -i /mnt/${YAML_FILE} -f /mnt/${BASE_NAME}\n\
asciidoctor -a toc=left -a toclevels=3 /mnt/${BASE_NAME}.adoc\n\
exit 0' > /opt/entrypoint.sh && chmod 755 /opt/entrypoint.sh

ENTRYPOINT ["/opt/entrypoint.sh"]