springfoxを利用してみる

以下の依存を追加します

implementation 'io.springfox:springfox-boot-starter:3.0.0'

SpringBootのバージョンによって起動時にエラーになってしまうのですが、application.yamlに以下のような記載をすれば問題ありません。

spring:
  mvc:
    pathmatch:
      matching-strategy: ant-path-matcher

以下のようなコントローラーを定義しておきました

@RestController
public class ItemController {

    @GetMapping("/items")
    public List<Item> getItems(){
        return List.of(new Item(1,"洗剤"), new Item(2, "コップ"));
    }

    @GetMapping("/item/{id}")
    public Item getItem(@PathVariable int id){
        return new Item(id,"冷蔵庫");
    }

    @PostMapping("/item/save/{itemId}/{itemName}")
    public Item saveItem(@PathVariable int itemId, @PathVariable String itemName){
        return new Item(itemId,itemName);
    }
}

以下にアクセスするとswaggeruiが確認できます。

ttp://localhost:8080/swagger-ui/

item-controllerにあるメソッドが定義されています。更にserversは起動しているローカルホストが指定されています。

試しにtryをすると実際にアプリケーションが処理をしてくれます。

個別エンドポイントのカスタマイズ

個別エンドポイントはメソッド名が表示されているなど、APIの定義書としては不十分なところがあるかもしれません。

アノテーションを付与することでカスタマイズできます

@RestController
public class ItemController {

    @GetMapping("/items")
    public List<Item> getItems(){
        return List.of(new Item(1,"洗剤"), new Item(2, "コップ"));
    }
    
    @ApiOperation(value="個別アイテム情報取得", notes="アイテム情報をIDから取得します。",
            httpMethod = "GET", consumes = "application/json", response = Item.class
    )
    @ApiResponse(code = 200, message = "取得したアイテム情報", response = Item.class)
    @GetMapping("/item/{id}")
    public Item getItem(@PathVariable int id){
        return new Item(id,"冷蔵庫");
    }
    
    @ApiOperation(value = "アイテム情報作成", notes = "アイテム情報を新規に作成します",httpMethod = "POST",
            consumes = "application/json")
    @PostMapping("/item/save/{itemId}/{itemName}")
    public Item saveItem(@PathVariable int itemId, @PathVariable String itemName){
        return new Item(itemId,itemName);
    }
}

個別エンドポイントをカスタマイズできていることがわかります。

API定義書の設定

API定義のタイトルとかが不自然なので修正します

以下のようなコンフィグクラスを作成します

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo());
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("アイテムAPI")
                .description("アイテムの取得、作成を行うAPIです")
                .version("1.0")
                .contact(new Contact("misakamikoto","https://volkruss.com/","misaka@mikoto.com"))
                .build();
    }
}

以下のようにAPI定義書のタイトルなどが修正されています

静的ドキュメントの生成

SwaggerからAsciiDocへの変換を行うのに、Swagger2Markupというのがあり、Swagger2MarkupをSpring用にカスタマイズしたものがspringfox-statcidocsです。

以下の依存を追加しておきます

testImplementation 'io.springfox:springfox-staticdocs:2.6.1'

以下のようなテストコードを作成してスぺニットを作成します。なぜテストかというと、テストにしておけばビルド時に自動で実行されるためです。

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
import org.springframework.web.context.WebApplicationContext;
import springfox.documentation.staticdocs.Swagger2MarkupResultHandler;

import static org.junit.jupiter.api.Assertions.*;

@SpringBootTest
@AutoConfigureMockMvc
public class MakeApiDocTest {

    @Autowired
    private WebApplicationContext context;

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void test_make_apidoc() throws Exception {
        this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(Swagger2MarkupResultHandler.outputDirectory("build/asciidoc/snippets").build())
                .andExpect(status().isOk());
    }
}

APIのパラメータを使ったときにgetDefaultValueでエラーになってしまいました。→テスト実施時

'java.lang.String io.swagger.models.parameters.AbstractSerializableParameter.getDefaultValue()'
java.lang.NoSuchMethodError: 'java.lang.String io.swagger.models.parameters.AbstractSerializableParameter.getDefaultValue()'
	at io.github.robwin.swagger2markup.utils.ParameterUtils.getDefaultValue(ParameterUtils.java:108)

メソッドがないよと怒られていますが、エラー個所を見ると…

public static String getDefaultValue(Parameter parameter){
    Validate.notNull(parameter, "property must not be null!");
    String defaultValue = "";
    if(parameter instanceof AbstractSerializableParameter){
        AbstractSerializableParameter serializableParameter = (AbstractSerializableParameter)parameter;
        defaultValue = serializableParameter.getDefaultValue();
    }
    return defaultString(defaultValue);
}

これはgetDefaultValueの戻り値がObjectになっています。おそらくバージョンによっては発生しないエラーなんだと思います。しかし、こればっかりは修正しようがないような気がするので、一旦はドキュメントの生成だけに着眼します。

https://github.com/Swagger2Markup/swagger2markup/issues/289

コントローラーを一旦以下のようにしておきます

@RestController
public class ItemController {

    @GetMapping("/items")
    public List<Item> getItems(){
        return List.of(new Item(1,"洗剤"), new Item(2, "コップ"));
    }
}

これでエラー無くテストは実施でき、成功後は指定したフォルダに3つのファイルが出力されています。

生成されたadocファイルはGradleプラグインのasciidoctorでhtmlに変換します。

gradleプラグイン設定するために、build.gradleを以下のようにします

plugins {
	id 'org.springframework.boot' version '2.7.4'
	id 'io.spring.dependency-management' version '1.0.14.RELEASE'
	id 'java'
	id "org.asciidoctor.jvm.convert" version "3.3.2" // 最新バージョンにする（じゃないとエラーになります）
}

group = 'com.volkruss'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	implementation files('libs/MisakaDatabase-1.0-SNAPSHOT.jar')
	implementation 'io.springfox:springfox-boot-starter:3.0.0'
	// https://mvnrepository.com/artifact/io.springfox/springfox-staticdocs
	testImplementation 'io.springfox:springfox-staticdocs:2.6.1'

}

tasks.named('test') {
	useJUnitPlatform()
}

// 追加
asciidoctor {
	dependsOn test
	sourceDir file('build/asciidoc/snippets')
	outputDir file('build/docs')
}

pluginsにorg.asciidoctor.jvm.convertを追加する
asciidoctorタスクの設定を追加する
- テスト後に実施する
- adocファイルがあるパスの指定をする
- htmlを出力するパスの指定をする

タスクを実行すると以下のようにHTMLファイルが出力されます

HTMLはこんな感じで出力されていました

終わりに

Springではバージョンによってバグ？があったりで使う気にはなれませんでした。またアノテーションでごちゃごちゃになるのも好きではないです。

springfoxでSwaggerを使い、静的ファイル出力する