こんにちは。阪本です。
世の中、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
オフライン仕様書生成
上記はアプリを起動しないと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ファイルが生成されます。
なんとなく、それっぽいドキュメントができました＾＾；
おわりに
とりあえず、ソースコードからREST API仕様書を生成できましたが、パラメータの桁数やフォーマットなど、「仕様書」としてはまだまだ情報が不足しています。
次回は、そのあたりの詳細情報の出力について、確認してみたいと思います。
それではー。
Acroquest Technologyでは、キャリア採用を行っています。
- 日頃勉強している成果を、AWS、Hadoop、Storm、NoSQL、SpringBoot、HTML5/CSS3/JavaScriptといった最新の技術を使ったプロジェクトで発揮したい。
- 社会貢献性の高いプロジェクトに提案からリリースまで携わりたい。
- 書籍・雑誌等の執筆や対外的な勉強会の開催を通した技術の発信や、社内勉強会での技術情報共有により、技術的に成長したい。
- OSSの開発に携わりたい。
少しでも上記に興味を持たれた方は、是非以下のページをご覧ください。
キャリア採用ページ
