{"componentChunkName":"component---src-templates-blog-post-js","path":"/swagger-codegen-1/","result":{"data":{"site":{"siteMetadata":{"title":"/dev/yukarinoki"}},"markdownRemark":{"id":"9be42dc5-0c73-5b98-ad01-f4e245b131ac","excerpt":"swagger SwaggerはAPIの仕様記述言語とツール群です。APIの仕様書をYAMLまたはJSONの形式で記述し、Swagger EditorやSwagger UIを使って可視化・共有することができます。 そして、ちょっとすごいところはSwaggerで書かれたAPI…","html":"

swagger

\n

SwaggerはAPIの仕様記述言語とツール群です。APIの仕様書をYAMLまたはJSONの形式で記述し、Swagger EditorやSwagger UIを使って可視化・共有することができます。

\n

そして、ちょっとすごいところはSwaggerで書かれたAPI記述をサーバーのコード、クライアントのコードに変換することができます。そのためのツールがswagger-codegenです。

\n

swagger-codegen

\n

swagger-codegen\nhttps://github.com/swagger-api/swagger-codegen

\n

swagger-codegenには、goやnodejsをはじめとした複数の言語やフレームワークを対象としたバックエンドを含んでいます。今回はtype-scriptのaxiosクライアント、nodejsのサーバーコードを生成してみました。

\n

手順

\n

cloneとbranchの切り替え

\n

まず、swagger-codegen をクローンします。\nクローンできたら、branchを自分のopenapi記述のバージョンによって切り替えます。\nopenapi2.0ならmaster、openapi3.0なら3.0.0です。私は3.0.0のブランチを利用しています。\n私は、最新コミットでやりましたが、バージョンを固定したい方は適当なTagにcheckoutしてください。\n僕はcommit 8f191f46a853bed86debc74f10f242712ae4758eでやっています。

\n

build swagger-codegen

\n

いくつかのbuild方法がありますが、Dockerを使うのが最も簡単な方法だと思います。\nDockerのイメージのビルド、swagger-codegenのビルドを一括でやってくれるshellスクリプトが用意されています。

\n
./run-in-docker.sh mvn package
\n

5分ぐらいでビルド完了して以下の出力が出ます。

\n
[INFO] ------------------------------------------------------------------------\n[INFO] Reactor Summary for swagger-codegen-project 3.0.38-SNAPSHOT:\n[INFO] \n[INFO] swagger-codegen-project ............................ SUCCESS [ 11.138 s]\n[INFO] swagger-codegen (core library) ..................... SUCCESS [03:25 min]\n[INFO] swagger-codegen (executable) ....................... SUCCESS [ 23.943 s]\n[INFO] swagger-codegen (maven-plugin) ..................... SUCCESS [ 10.012 s]\n[INFO] swagger-generator .................................. SUCCESS [01:19 min]\n[INFO] ------------------------------------------------------------------------\n[INFO] BUILD SUCCESS\n[INFO] ------------------------------------------------------------------------\n[INFO] Total time:  05:31 min\n[INFO] Finished at: 2023-01-21T04:56:44Z\n[INFO] ------------------------------------------------------------------------
\n

これが出れば成功です。

\n

試しに、./run-in-docker.sh langsを実行してみましょう。利用可能なバックエンドの一覧が表示されるはずです。

\n
{your host name}@ swagger-codegen % ./run-in-docker.sh langs                     \n++ dirname ./run-in-docker.sh\n+ cd .\n+ maven_cache_repo=/Users/{your host name}/.m2/repository\n+ mkdir -p /Users/nao/.m2/repository\n++ id -u\n++ id -g\n+ docker run --rm -it -w /gen -e GEN_DIR=/gen -e MAVEN_CONFIG=/var/maven/.m2 -u 501:20 -v /Users/nao/test/swagger-codegen:/gen -v /Users/nao/.m2/repository:/var/maven/.m2/repository --entrypoint /gen/docker-entrypoint.sh maven:3-jdk-8 langs\nAvailable languages: [dart, aspnetcore, csharp, csharp-dotnet2, go, go-server, dynamic-html, html, html2, java, jaxrs-cxf-client, jaxrs-cxf, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs-jersey, jaxrs-di, jaxrs-resteasy-eap, jaxrs-resteasy, micronaut, spring, nodejs-server, openapi, openapi-yaml, kotlin-client, kotlin-server, php, python, python-flask, r, ruby, scala, scala-akka-http-server, swift3, swift4, swift5, typescript-angular, typescript-axios, typescript-fetch, javascript]
\n

openapi.yamlからコードをgenerate

\n

今回利用するbackendは、clientがtypescript-axios、backendがnodejs-serverです。clientは複数の選択肢がありますが、serverはjavascript(typescript)ならnodejs-serverしか選択肢がないようです。

\n

まず、自分の作成したopenapi.yamlをswagger-codegenの直下にコピーします。\nその上で、以下を実行します。

\n
./run-in-docker.sh generate -i openapi.yaml \\\n    -l typescript-axios -o /gen/out/test-client -DpackageName=test-client # client\n\n./run-in-docker.sh generate -i openapi.yaml \\\n    -l nodejs-server -o /gen/out/test-server -DpackageName=test-server # server
\n

すると以下のような出力が出て、生成が完了します。

\n
...\n05:00:38.447 [Thread-1] INFO  i.s.codegen.v3.AbstractGenerator - writing file /gen/out/test-client/tsconfig.json\n05:00:38.459 [Thread-1] INFO  i.s.codegen.v3.AbstractGenerator - writing file /gen/out/test-client/.swagger-codegen-ignore\n05:00:38.470 [Thread-1] INFO  i.s.codegen.v3.AbstractGenerator - writing file /gen/out/test-client/.swagger-codegen/VERSION
\n

swagger-codegen/out/test-{client, server}に出力されたコードがあるはずです。

\n

実行

\n

生成された各ディレクトリにREADME.mdがあります。そこにどうやって生成コードを実行すればいいのか書いてあります。\n今回の場合、どちらとも以下です。

\n
npm install\nnpm start
\n

これで実行できました。

\n

まとめ

\n

今回は、swagger-codegenを使ってopenapi記述から、javascriptのclient, serverのコードを生成してみました。もちろん、実装上必要なコード全てが生成できるわけではありませんが、参考にするには十分なコードが生成されていると思います。このコードをパーツとして切り貼りして開発すれば、実装の速度や正確性も向上するのではないかと思っています。

","tableOfContents":"","frontmatter":{"title":"swager-codegenのまともな使い方","date":"January 22, 2023","description":""}}},"pageContext":{"slug":"/swagger-codegen-1/","previous":{"fields":{"slug":"/ante_compile/"},"frontmatter":{"title":"Anteをコンパイルするときの謎つまづきポイント"}},"next":{"fields":{"slug":"/polymarket-binary-options-intro/"},"frontmatter":{"title":"How Binary Options Work on Prediction Markets: A Developer's Introduction to Polymarket Contracts"}}}}}