【技術メモ】SpringMVCのAPI仕様書をSwagger使って自動生成する

SwaggerでAPI仕様書を自動生成

前書き

Swagger-uiの動的ドキュメントにする手順はたくさん出てくるのに、静的なHTMLにする手順があんまり見つからない

基本的には、以下のブログの焼き直しです、省略されている内容を個人的に思い出せるように補足しつつメモです

iktakahiro.hatenablog.com

概要

1. ソースコードにSwaggerを導入
2. Swagger定義ファイルを出力
3. Swagger定義ファイルからascii-docを出力
4. ascii-docをHTMLに変換

前提

Swagger

• swagger-core
  • ソースコードからswagger.jsonを生成
• spring-fox
  • swagger-coreのSpring用実装
• swagger-ui
  • swagger.jsonから仕様書を生成

Swaggerの概念図はこれがみやすい

blog.takuros.net

SpringFox

• 一連のSpringプロジェクトで作成されたWeb APIの仕様書を自動で生成してくれるライブラリ
• Springfoxは、実行時に一度アプリケーションをスキャンして、Springの設定、クラス構造、その他様々なコンパイル時に基づくAPIのセマンティクスを推論します。
• SpringFoxはもともとswagger-springmvcという名前だった

Spring Boot + SpringFoxでSwaggerを利用してソースからAPIキュメントを生成する

Swaggerを導入

Mavenの依存性を追加

<dependencies>
         <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-core</artifactId>
    <version>1.5.4</version>
</dependency>
</dependencies>

JavaConfigファイルを作成

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket document() {
        return new Docket(DocumentationType.SWAGGER_2).select().paths(PathSelectors.any()).build().apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Example API").version("1.0").build();
    }
}

Configの説明はこちらも参照させてもらった方がよさそう

pppurple.hatenablog.com

---

Swagger定義ファイルを出力

• SpringBootを起動
• Swagger-uiにアクセス
  • http://localhost:8080/
• swagger.jsonを表示
  • ヘッダ部分のプルダウンに表示されているURLを実行
  • 例：http://localhost:8080/v2/api-docs/

How to generate swagger.json

---

Swagger定義ファイルからascii-docを出力

swagger2markup-cliにおまかせ

github.com

• GitHub からクローン
• gradleビルドしてjarを生成
• jarを実行

### 
$ git clone https://github.com/Swagger2Markup/swagger2markup-cli.git
### 
$ cd swagger2markup-cli
$ gradle assemble
### 
$ cd build/libs/
$  java -jar swagger2markup-cli-1.3.3.jar convert -i sample.json -f api-doc

---

ascii-docをHTMLに変換

asciidoctorにおまかせ

github.com

### gemでインストール
$ sudo gem install asciidoctor
### asciidoctor実行
$ asciidoctor -a toc=left api-doc.adoc 
### ブラウザで表示
$ open "/Applications/Google Chrome.app" api-doc.html 

Gradleで実行もできるらしい

PlantUML 埋め込み AsciiDoc の Gradle を用いた HTML 一括変換 · Yutaka 🍊 Kato

さらにAWSで。ここまでやりたい。

AsciiDocの文書をCodePipeline/CodeBuildでHTMLに変換してみた ｜ DevelopersIO

---

参考リンク

qiita.com

---