Swagger YAMLファイルをHTMLへ変換するdocker image

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 imageを作成しています。詳細はDockerHubのリポジトリnmatsui/swagger2htmlを参照してください。

FROM alpine:3.7
MAINTAINER Nobuyuki Matsui <[e-mail]>

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"]