Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Swagger Codegenで APIクライアントgem 自動生成 #m3kt

Swagger Codegenで APIクライアントgem 自動生成 #m3kt

Jumpei Takiyasu

September 28, 2017
Tweet

More Decks by Jumpei Takiyasu

Other Decks in Programming

Transcript

  1. Swagger Tools Swagger Definition(spec file)を生成・パースするツール群 Swagger definition (spec file) API

    ドキュメント サーバ スタブ サーバ実装 クライアント ライブラリ Swagger Core Swagger UI Swagger Codegen Swagger Editor 手入力 今回説明したいのは下半分のフロー
  2. Spring bootと使うには? Spring Boot サーバ実装 クライアント ライブラリ Swagger Core Swagger

    Codegen Springfox Springの実装とSwagger Coreを使い、spec fileを生成する Swagger definition (spec file)
  3. Docket = APIのグループを定義して、タイトルや属性などを追加 Springfoxの使い方 @EnableSwagger2 class SpringfoxConfig { @Bean fun

    demoApiDocument(): Docket { return Docket(DocumentationType.SWAGGER_2) .groupName("springfox") .select() .paths(PathSelectors.ant("/demo/**")) .build() } ...
  4. config.json 独自テンプレートを使う場合 コマンド例 java -jar swagger-codegen-cli.jar generate \ --api-package package-name

    \ -o /path/to/outputdir \ -l ruby \ -i http://localhost:8080/v2/api-docs?group=target-api \ -c config.json \ -t /path/to/template { "gemName": "api-client", "moduleName": "ApiClient", "gemVersion": "1.0.0" }
  5. OperationIdにsuffixがつく OperationId:クライアントgemの関数名になるパラメータ • 複数Docketから参照されている • 別クラスにが同名の定義ある Kotlin spec file "paths":

    { "/demo/user/{id}": { "get": { "tags": [ "demo-controller" ], "summary": "getUser", "operationId": "getUserUsingGET_1", … } @RestController @RequestMapping("/demo") class DemoController { @GetMapping("/user/{id}") fun getUser(@PathVariable id: Int): userApiParam { … }
  6. Nested Class名が重複すると静かに壊れる "AdminApiParam": { "type": "object", "properties": { "info": {

    "$ref": "#/definitions/Info" } } }, "UserApiParam": { "type": "object", "properties": { "info": { "$ref": "#/definitions/Info" } } } class AdminApiParam( val info: Info ) { class Info( val secretInfo: String, val region: String ) } class UserApiParam( val info: Info ) { class Info(val region: String) } Kotlin spec file ビルドが通ってgemも生成されるが、動かなくなる
  7. Springfennec Swagger spec generator from Spring annotations, written in Kotlin

    https://github.com/juntaki/springfennec Springの実装とSwagger annotationから、 Annotation processorでビルド時にspec fileを生成する つくりました
  8. 使い方 @ApiGroup annotationと、dependenciesを書き足す。 build.gradle Kotlin dependencies { ... // Springfennec

    def springfennecVersion = 'x.x.x' compile('io.swagger:swagger-core:1.5.16') compile("com.juntaki:springfennec:${springfennecVersion}") kapt("com.juntaki:springfennec:${springfennecVersion}") ... } @ApiGroup(value="^/pet/.*", // regex for path (not include basePath) name = "pet_api", // output will be spec_${name}.json, e.g. spec_pet_api.json apiInfo = @SwaggerDefinition(...))