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

SwaggerのYAMLファイルは、[Swagger Editor](https://editor.swagger.io)で書く上ではビジュアルに表示されて幸せですが、偉い人たちに報告する際に「Swagger Editor入れてね！」とは言いづらいものです。

そこで @fanfanta の[SwaggerファイルをHTMLへ変換する](https://qiita.com/fanfanta/items/47b5a79d8a9d3736b7eb)を参考に、SwaggerのYAMLファイルをHTMLに一発変換するdocker imageを作成しました。

# 編集履歴

0.2.0: swagger2markupのプロパティをカスタマイズできるようにしました。
0.3.0: サイドバーの目次をタグでグルーピングするように変更しました。

# 利用方法

SwaggerのYAMLファイルがあるディレクトリで、次のコマンドを実行してください。

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

Swagger YAMLファイルから生成したAsciiDoc形式のファイルと、HTMLファイルが同じディレクトリに生成されます。

![petstore.html.png](https://qiita-image-store.s3.amazonaws.com/0/37648/43eec34d-7e14-5b19-b9fd-851c4612f144.png)


## swagger2markupのプロパティ

このDockerfileが利用している[swagger2markup](https://github.com/Swagger2Markup/swagger2markup-cli)には、変換時の挙動を制御するプロパティを与えることができます。
デフォルトで与えるプロパティは以下となりますが、SwaggerのYAMLファイルと同じディレクトリに `swagger2markup.properties` という名前でプロパティファイルを作っておくと、そのプロパティファイルを使って変換を行います。

```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](https://github.com/Swagger2Markup/swagger2markup/blob/master/src/docs/asciidoc/usage_guide.adoc)を参照してください。

## asciidoctorの引数

swagger2markupが生成したAsciiDoc形式のドキュメントを、[asciidoctor](https://asciidoctor.org/)を用いてHTML化しています。色々CSSをカスタマイズしたりもできますが、今回はdepth3までの目次を出す引数を与えているだけです。

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

# Dockerfile

[alpine Linux 3.7](https://alpinelinux.org/posts/Alpine-3.7.0-released.html)をベースにDocker imageを作成しています。詳細はDockerHubのリポジトリ[nmatsui/swagger2html](https://hub.docker.com/r/nmatsui/swagger2html/)を参照してください。

```dockerfile
FROM alpine:3.7
MAINTAINER Nobuyuki Matsui <nobuyuki.matsui@gmail.com>

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