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

De059f612e2f68589831e4bde0f15c83?s=47 Jumpei Takiyasu
September 28, 2017

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

De059f612e2f68589831e4bde0f15c83?s=128

Jumpei Takiyasu

September 28, 2017
Tweet

Transcript

  1. 10.

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

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

    Spring bootと使うには? Spring Boot サーバ実装 クライアント ライブラリ Swagger Core Swagger

    Codegen Springfox Springの実装とSwagger Coreを使い、spec fileを生成する Swagger definition (spec file)
  3. 12.

    Docket = APIのグループを定義して、タイトルや属性などを追加 Springfoxの使い方 @EnableSwagger2 class SpringfoxConfig { @Bean fun

    demoApiDocument(): Docket { return Docket(DocumentationType.SWAGGER_2) .groupName("springfox") .select() .paths(PathSelectors.ant("/demo/**")) .build() } ...
  4. 14.

    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. 17.

    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. 19.

    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. 26.

    Springfennec Swagger spec generator from Spring annotations, written in Kotlin

    https://github.com/juntaki/springfennec Springの実装とSwagger annotationから、 Annotation processorでビルド時にspec fileを生成する つくりました
  8. 28.

    使い方 @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(...))