Taste of Tech Topics

Acroquest Technology株式会社のエンジニアが書く技術ブログ

Springfox+Swagger+Bootprintによる即席REST API仕様書作成

こんにちは。阪本です。

世の中、Swagger注目を浴びてきていますね。
開発のスピードアップが求められる中、「外部IF仕様書なんて書いてられねぇ!!」なんて言って実装をバリバリ進めてしまいそうですが(アカンアカン)、そうは言っても外部IF、他社との仕様調整も必要。

そんなときに有効な、実装しながら仕様書も作れるSpringfox+Swaggerに加え、ドキュメント生成ツールのBootprintを使って、簡易的な仕様書を作ってみました。

仕様書の動的生成

以下のようなシンプルなSpringBootアプリケーションから、REST APIを生成してみます。

@SpringBootApplication
public class SwaggerExampleMain {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerExampleMain.class, args);
    }
}
@RestController
@RequestMapping("/employee")
public class EmployeeController {
	
    @RequestMapping(method = RequestMethod.GET)
    public List<Employee> list() {
        // Return employee list
        return new ArrayList<>();
    }

    @RequestMapping(method = RequestMethod.POST)
    public void create(@RequestBody Employee employee) {
        // Add employee
    }

    @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
    public void update(@PathVariable Integer id,
            @RequestBody Employee employee) {
        // Update employee
    }

    @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
    public void delete(@PathVariable Integer id) {
        // Delete employee
    }
}

まずはpom.xml。Springfoxを追加します。

<springfox.version>2.2.2</springfox.version>

~~~

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>${springfox.version}</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>${springfox.version}</version>
</dependency>

そして、Swaggerの設定を行うJavaConfigクラスを作成します。
@EnableSwagger2アノテーションを付けて、Docketでいろいろ指定するところがミソです。
今回は、「/error」以外のURIを持つREST APIのドキュメントを一覧化することにします。

import static springfox.documentation.builders.PathSelectors.regex;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket documentation() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(
                RequestHandlerSelectors.any()).paths(
                        regex("^/(?!error).*$")).build().pathMapping("/").apiInfo(metadata());
    }

    @Bean
    public UiConfiguration uiConfig() {
        return UiConfiguration.DEFAULT;
    }

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

これらを書いて、Javaアプリを普通に起動するだけで、APIの一覧とパラメータが見えるようになります。
http://localhost:8080/swagger-ui.html

f:id:acro-engineer:20151202021445p:plain

さらに、この画面でAPIに対してリクエストを送信することもできます。
簡易的な動作確認をするにも便利ですね。

オフライン仕様書生成

上記はアプリを起動しないとAPIの情報が見られませんでしたが、顧客や他チームと共有できる環境がなく恵まれない場合もあります。
そんなときは、オフラインの仕様書を生成しましょう。

オフラインの仕様書はSpringfoxでもMarkdown形式で生成できますが、ここはあえてMarkdownドキュメントが見られない(ツールなんて入れてない)人のことも想定し、HTML形式で出してみます。

Swagger2Markupという選択肢もありましたが、何となく使うのが大変そうだったので、今回はbootprint-swaggerを使ってみます。


node.jsをインストールした環境で以下のコマンドを実行し、bootprint-swaggerをインストールします。

npm install -g bootprint
npm install -g bootprint-swagger

Springfoxの設定を行ったJavaアプリを立ち上げ、bootprint-swaggerを実行します。

bootprint swagger http://localhost:8080/v2/api-docs target

これにより、targetフォルダ配下にHTMLファイルが生成されます。

f:id:acro-engineer:20151202021450p:plain

なんとなく、それっぽいドキュメントができました^^;

おわりに

とりあえず、ソースコードからREST API仕様書を生成できましたが、パラメータの桁数やフォーマットなど、「仕様書」としてはまだまだ情報が不足しています。
次回は、そのあたりの詳細情報の出力について、確認してみたいと思います。

それではー。

Acroquest Technologyでは、キャリア採用を行っています。


  • 日頃勉強している成果を、AWSHadoop、Storm、NoSQL、SpringBoot、HTML5/CSS3/JavaScriptといった最新の技術を使ったプロジェクトで発揮したい。
  • 社会貢献性の高いプロジェクトに提案からリリースまで携わりたい。
  • 書籍・雑誌等の執筆や対外的な勉強会の開催を通した技術の発信や、社内勉強会での技術情報共有により、技術的に成長したい。
  • OSSの開発に携わりたい。

 
少しでも上記に興味を持たれた方は、是非以下のページをご覧ください。
 キャリア採用ページ