SwaggerはRESTful APIの設計、構築、文書化、テストを支援するオープンソースフレームワークです。本記事では、Spring BootプロジェクトにおけるSwaggerの実装手順を紹介します。

主要機能

• APIドキュメントを自動生成し、コード変更に応じて自動更新
• ブラウザ上でAPIの直接実行とテストが可能
• Java、Python、JavaScriptなど多言語に対応

必要なライブラリ

SpringfoxはSwaggerとSpring Bootの統合を実現するライブラリで、以下のコンポーネントを含みます：

• springfox-swagger2 - Swaggerコア機能
• springfox-swagger-ui - ドキュメント表示インタフェース

工程1：Maven依存関係の追加

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

工程2：サンプルコントローラーの作成

@RestController
public class SampleController {
    @RequestMapping("/greet")
    public String greet() {
        return "Hello World";
    }
}

工程3：Swagger設定クラスの追加

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
}

工程4：Docket Beanの設定

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(configureApiInfo());
    }
    
    private ApiInfo configureApiInfo() {
        Contact contact = new Contact(
            "TechCorp", 
            "https://techcorp.example.com", 
            "support@techcorp.example.com"
        );
        
        return new ApiInfo(
            "API ドキュメント",
            "プロジェクトの詳細説明",
            "v2.0",
            "https://techcorp.example.com/terms",
            contact,
            "MIT License",
            "https://opensource.org/licenses/MIT",
            new ArrayList<>()
        );
    }
}

工程5：APIスキャン範囲の制御

@Bean
public Docket apiDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(configureApiInfo())
            .enable(true)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.myapp.controller"))
            .paths(PathSelectors.any())
            .build();
}

RequestHandlerSelectorsでは以下のスキャンモードが選択可能：

• basePackage() - 特定パッケージのスキャン
• any() - 全コントローラを対象
• withClassAnnotation() - 特定クラスアノテーションを持つもののみ
• withMethodAnnotation() - 特定メソッドアノテーションを持つもののみ

工程6：環境別のSwagger有効化

@Bean
public Docket apiDocket(Environment environment) {
    Profiles activeProfiles = Profiles.of("development", "staging");
    boolean isSwaggerEnabled = environment.acceptsProfiles(activeProfiles);
    
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(configureApiInfo())
            .enable(isSwaggerEnabled)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.myapp.controller"))
            .build();
}

工程7：ドキュメントグループの設定

@Bean
public Docket adminGroupDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("管理API");
}

@Bean
public Docket publicGroupDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("公開API");
}

工程8：アノテーションによるドキュメント拡張

@RestController
public class UserController {
    
    @GetMapping("/welcome")
    public String welcome() {
        return "Welcome!";
    }
    
    @ApiOperation("ユーザー情報の取得")
    @PostMapping("/user")
    public User getUser() {
        return new User();
    }
    
    @ApiOperation("ユーザー名の更新テスト")
    @PostMapping("/update")
    public String updateUser(@ApiParam("新しいユーザー名") String username) {
        return "Updated: " + username;
    }
    
    @PostMapping("/create")
    public User createUser(User user) {
        return user;
    }
}

@ApiModel("ユーザーエンティティ")
public class User {
    @ApiModelProperty("ユーザーID")
    private Long id;
    
    @ApiModelProperty("ユーザー名")
    private String username;
    
    // ゲッターとセッター
}

主要アノテーション一覧：

• @ApiModel - モデルクラスの説明を定義
• @ApiModelProperty - プロパティの説明を付与
• @ApiOperation - APIエンドポイントの説明
• @ApiParam - メソッドパラメータの説明