Serverless Frameworkでデプロイしたサービスからswagger.jsonを作りSDKやドキュメントを生成する
先日の続きです。
前回はServerless Frameworkを使ってAPI Gatewayでサービスを公開してみる、というところまでやりました。
個人や自分のチームだけが使ってメンテナンスするシングルサービスで構成されるアプリケーションならこれでガンガン開発すれば良いと思います。ただ、ものによってはチームで複数のサービスから構成される複雑なシステムを作る、といったケースや、外部に公開するAPIをもつサービスの一部としてこれらのサービスを開発する、というケースも想定されます。このような場合に必要なのが、開発者向けのドキュメントやクライアントライブラリを提供することです。
今回はそのあたりの整備をやっていきたいと思います。例によってリポジトリはここです。
一つ増えていますが、これはクライアントライブラリなどの開発者アセットの生成と配備を行うLambdaファンクション群をまとめたプロジェクトです。複数のプロジェクトから使い回せるように別プロジェクトに分けてあります。
最終的には、Github(merge)-> CodeBuild -> CodeDeploy -(API Gateway)-> クライアントライブラリの生成とSwagger UIの更新、みたいな流れををCodePipelineで作りたいわけですが、長くなったので最後の「クライアントライブラリの生成とSwagger UIの更新」の部分にフォーカスしています。
とりあえず、何をするにしてもswaggerファイルがあれば勝てると思うのでそこを目指すことにしましょう。
API GatewayからSwaggerファイルをエクスポートする
API GatewayのAPIにはSwaggerファイルの形式でエクスポートするための get-export
があるのでそれを使います。REST APIもありますが、Lambdaで叩こうと思うのでboto3を使っています。
import boto3 import os import logging apigateway = boto3.client('apigateway') s3 = boto3.resource('s3') def generate_swagger(event, context): try: staged_api = [api for api in apigateway.get_rest_apis()['items'] if api['name'] == os.environ['REST_API_NAME']].pop() exported_api = apigateway.get_export( restApiId=staged_api['id'], stageName=os.environ['REST_API_STAGE_NAME'], exportType="swagger" ) swagger_bucket = s3.Bucket(os.environ['SWAGGER_FILE_BUCKET']) swagger_file = swagger_bucket.Object('swagger.json') swagger_file.put( Body=exported_api['body'].read().decode('utf-8'), ContentEncoding='utf-8', ContentType='text/plane', ACL='public-read' ) return "/".join(["https://s3-ap-northeast-1.amazonaws.com", os.environ['SWAGGER_FILE_BUCKET'], "swagger.json"]) except Exception as e: logging.error("Generate Swagger-File Failed. Detail:{0}".format(e)) raise Exception("Coudn't create swagger file. Detail:{0}".format(e))
apigateway.get_export
をキックする前に apigateway.get_rest_apis
を叩いているのは、 get_export
でのAPI指定にIDが必要で、 serverless.yml
に書かれている設定だけではまかなえなかったからです。これについてはデプロイする環境名など、アプリケーションの情報を使うのでアプリケーション内に含まれるLambdaファンクションとしています。
ちなみに、これは後々ElasticBeanstalkで立てるSwagger GeneratorがURLでアクセスする必要があるのでアクセス権を public-read
にしています。
(当たり前だけど)ローカル実行時のユーザとデプロイ時のユーザが違うので注意
Serverless Frameworkにはローカル実行オプションがあって、リソースへのアクセスさえできればデプロイせずにも実行できるのですが、実行ユーザに関する注意点があることに今更気づきました。ローカル実行時のユーザが割と強い権限なので、 serverless.yml
に権限つけ忘れても動いてしまうんですよね。で、デプロイして実行たら権限が足りなくてこける、という(デプロイ自体は成功する)。
今回は、API Gateway関連の権限をつけ忘れていたので、以下を参考にしました。
APIドキュメントを充実させる
ちなみに、普通にServerless Framework使っているだけの状態でSwaggerファイルを生成しても、連携するもしくはユーザになる開発者に有用なアセットを作ることができません。エンドポイントの説明とかモデルの定義とかが空の状態のままなんですね。というわけで、APIドキュメントを充実させるために以下のプラグインを導入します。
基本的な使い方はドキュメントに書いてある通りなんですが、statusCodeはstringを要求されるみたいなので気をつけましょう。
Swaggerの定義では、リクエスト/レスポンスのモデルをJsonSchemaで定義します。このプラグインでは、それらの定義を別ファイルに切り出しておくことができます。それが以下の部分です。
models: - name: "CreateLifeLogRequest" description: "ライフログを作成する時のリクエスト" contentType: "application/json" schema: "${file(models/create_life_log_request.json)}" - name: "LifeLog" description: "ライフログのモデル" contentType: "application/json" schema: "${file(models/lie_log.json)}"
実際のJsonSchemaの定義は以下。
{ "type": "object", "properties": { "event": { "description": "ライフイベントの内容を記載してください。", "type": "string" }, "insight": { "description": "ライフイベントが起こった時の感情を記載してください。(任意)", "type": "string" } }, "required": ["event"] }
で、モデルをJsonSchemaで表せるということは、Lambdaファンクション内でスキーマをベースにしたチェックができるということなんですね。
import json import logging import os import time import uuid import jsonschema from commons import aws_resources def create_life_log(event, context): try: dynamodb = aws_resources.get_dynamodb(event) timestamp = int(time.time() * 1000) data = json.loads(event['body']) request_schema = json.load(open(os.environ['REQUEST_MODEL_SCHEMA'])) jsonschema.validate(data, request_schema) table = dynamodb.Table(os.environ['LIFE_EVENT_TABLENAME']) item = { 'id': str(uuid.uuid1()), 'event': data['event'], 'createdAt': timestamp, 'updatedAt': timestamp } if 'insight' in data: item['insight'] = data['insight'] table.put_item(Item=item) response = { "statusCode": 200, "body": json.dumps(item) } return response except KeyError as e: logging.error("Validation Failed") raise Exception("Coudn't create life log.Detail:{0}".format(e)) return
jsonschema.validate(data, request_schema)
の部分がそれです。ちなみに、Lambdaの実行環境には jsonschema
は含まれていないので、プロジェクトにインストールしてデプロイ時のzipファイルに含まれるようにしてあげる必要があります。どうしようか迷ったんですが、とりあえずインストールした外部パッケージ自体はgitignoreには追加してます。
と、ここまで書きながら調べたら、 lambda-uploderというプラグインがあるんですね、今度使ってみたいと思います。
SwaggerファイルからSDKを作る
さて、ここからは生成したSwaggerファイルを活用していきます。Swaggerファイルから各種コード生成を行うためのSwagger Codegeneratorというツールがあるので、活用します。
https://swagger.io/swagger-codegen/swagger.io
これは、Dockerhubにある公式イメージで、ジェネレータをWebサービスとして起動可能なので、Elastic Beanstalkを使ってサービスを立てます。その時Dockerrun.aws.jsonは以下のような感じ。
{ "AWSEBDockerrunVersion": "1", "Image": { "Name": "swaggerapi/swagger-generator", "Update": true }, "Ports": [ { "ContainerPort": "8080" } ] }
例えばJavaのクライアントライブラリを生成したい場合は以下のようにリクエストしてください。
curl -X POST --header 'Content-type: application/json' --header 'Accept: application/json' -d '{"swaggerUrl": "swagger.jsonのURL"}' EBのURL/api/gen/clients/java
このAPIが請け負うのはライブラリの生成要求のみで、ダウンロードは別のAPIが用意されています。先のAPIの結果から code
を取得して以下のように投げます。
curl -X GET "EBのURL/api/gen/download/取得したcode" -H "accept: application/octet-stream" > library.zip
なお、これで生成されるライブラリのダウンロードはワンタイムな模様で、ダウンロードに失敗したら生成からやり直しが必要です。
これをLambdaファンクションとして書いたものが以下です。これは割と使い回せるので、別に配布用のサービスを作っています。
import json import os import boto3 import urllib.request s3 = boto3.resource('s3') def generate_client_api(swagger_url, language): api_base = { "url": "/".join([os.environ['SWAGGER_API_URL'], os.environ['GENERATE_CLIENT_URL'], language]), "method": "POST", "headers": {"Content-Type": "application/json"} } obj = {"swaggerUrl": swagger_url} json_data = json.dumps(obj).encode("utf-8") return urllib.request.Request(api_base['url'], data=json_data, method=api_base['method'], headers=api_base['headers']) def download_client_api(code): return "/".join([os.environ['SWAGGER_API_URL'], os.environ['DOWNLOAD_CLIENT_URL'], code]) def distribute_client(event, context): request = generate_client_api(event['swaggerUrl'], event['language']) with urllib.request.urlopen(request) as res: code = json.loads(res.read().decode('utf-8'))['code'] with urllib.request.urlopen(download_client_api(code)) as client_res: client_bucket = s3.Bucket(os.environ['CLIENT_SDK_BUCKET']) client_file = client_bucket.Object( event['serviceName'] + '/{0}/{0}-generated-client.zip'.format(event['language'])) client_file.put(Body=client_res.read()) response = { "statusCode": 200 } return response
Swaggerファイルの生成とクライアントの生成をStepFunctionsで繋ぐ
Swaggerファイルとクライアントの生成を個別にLambdaファンクションで行うことには成功しました。どうせならこの辺繋げたいですよね?
というわけでStep Functionsを使って繋げましょう。StepFunctionsとは、視覚的なワークフローを使って、コンポーネントやLambdaファンクションを繋ぐ分散アプリケーションを構築するためのサービスです。
前職時代にSOAPでこういうソリューションを使った記憶があって、大規模SIerが好きそうな感じがしすね。時代は巡る糸車。
ステートマシンという実行ワークフローを構築し、その中のタスクでLambdaの実行などをします。ステートマシンはjsonベースのAmazon State Languageで書かれるようです。
ドキュメントに日本語はありませんが、東京リージョンにもちゃんときているので、安心して使いましょう。なお、当然といえば当然ですが、さすがに同じアカウント内のLambdaファンクションじゃないとワークフローに使えません。
というわけで、こんな感じのStep Functionsを作りました。
{ "Comment": "Swaggerファイルの生成に成功したら、各言語向けにライブラリを生成する。", "StartAt": "SetServiceName", "States": { "SetServiceName": { "Comment": "サービス名の設定", "Type": "Pass", "Result": "my-assistant", "ResultPath": "$.serviceName", "Next": "GenerateSwaggerFile" }, "GenerateSwaggerFile": { "Type": "Task", "Comment": "Swaggerファイルの生成", "Resource": "Swaggerファイル生成のLambdaファンクションARN", "Catch": [{ "ErrorEquals": ["UnhandledError"], "Next": "GenerateErrorFallback" }], "ResultPath": "$.swaggerUrl", "Next": "GenerateClientParallel" }, "GenerateErrorFallback": { "Type": "Pass", "Result": "This is a fallback from a generate swagger file Lambda function exception", "End": true }, "GenerateClientParallel": { "Type": "Parallel", "End": true, "Branches": [ { "StartAt": "SetLanguageJava", "States": { "SetLanguageJava": { "Comment": "言語設定にJavaを追加する", "Type": "Pass", "Result": "java", "ResultPath": "$.language", "Next": "GenerateClientJava" }, "GenerateClientJava": { "Type": "Task", "Resource": "クライアント生成のLambdaファンクションARN", "InputPath": "$", "OutputPath": "$", "End": true } } }, { "StartAt": "SetLanguageRuby", "States": { "SetLanguageRuby": { "Comment": "言語設定にRubyを追加する", "Type": "Pass", "Result": "ruby", "ResultPath": "$.language", "Next": "GenerateClientRuby" }, "GenerateClientRuby": { "Type": "Task", "Resource": "クライアント生成のLambdaファンクションARN", "InputPath": "$", "OutputPath": "$", "End": true } } }, { "StartAt": "SetLanguageJavascript", "States": { "SetLanguageJavascript": { "Comment": "言語設定にJavaScriptを追加する", "Type": "Pass", "Result": "javascript", "ResultPath": "$.language", "Next": "GenerateClientJavaScript" }, "GenerateClientJavaScript": { "Type": "Task", "Resource": "クライアント生成のLambdaファンクションARN", "InputPath": "$", "OutputPath": "$", "End": true } } }, { "StartAt": "SetLanguageScala", "States": { "SetLanguageScala": { "Comment": "言語設定にScalaを追加する", "Type": "Pass", "Result": "scala", "ResultPath": "$.language", "Next": "GenerateClientScala" }, "GenerateClientScala": { "Type": "Task", "Resource": "クライアント生成のLambdaファンクションARN", "InputPath": "$", "OutputPath": "$", "End": true } } } ] } } }
Swaggerファイルの生成に成功したら、Java、Ruby、JavaScript、Scalaのクライアント生成をパラレルで実行するようにしています。Swaggerファイルの生成に失敗した場合はLambdaファンクションから例外を発生させて、それをキャッチしてStateMachinを止めるように作ってあります。カスタムエラーもドキュメントにはあるのですが、うまく動きませんでした。
ドキュメントを読む限りは、他には分岐やリトライなどもあり、基本的なワークフローは問題なく実装できそうです。
ただし、StateMachineのinputとoutputは特殊で慣れが必要だな、と感じました。StateMachine自体のInputとOutputを全てのタスクでコンテキストとして共有して、やりとりしている感じです。全てのタスクにはStateMachineのInputが渡されます。そのため、あるタスクの結果を後続タスクに曳き回したいときは、Inputの構成にそれを追加してあげる必要が出てきます。 GenerateSwaggerFile
タスクの "ResultPath": "$.swaggerUrl",
となってる箇所がその箇所です。このタスクの処理結果をInputの swaggerUrl
という属性に放り込んでいます。
ちなみに、Parallelで並列実行する場合は各ブランチごとにInput領域がコピーされるため、ブランチ内では独立してInput領域を扱うことができ、名前が被っても問題ありません。実行時に実際に渡されたInputを見てみましょう。Java生成ブランチでのものとRuby生成ブランチでのものです。
上記のように、同じInputの属性でも別々の値がセットされています。
StepFunctionsをServerlessフレームワークの設定として書く
ここまでくると、アプリケーションのサービスをデプロイしたらStep FunctionsのStateMachineも作って欲しいですよね?というわけで、こんなプラグインを導入しました。
このプラグインを導入すれば、 serverless.yml
にStep Functionsの設定をかけるようになります。基本的にはjson形式がyaml形式になるだけです。
ただ、StateMachineの登録される名前がちょっとあれでですね、今回の設定でデプロイしたらこんな感じになりました。
MyDashassistantDashgenerateDashclientDashdev-HJGGH29DKCX7
ちょっと待って、 -
を Dash
に変換されるとか望んでない。。。
SwaggerファイルからSwagger UIを作る
で、最後にSwagger UIなわけですが、これもswagger-uiもdockerイメージとして起動可能なのがわかったので、今回はちょっと省略させてもらいます。
https://hub.docker.com/r/swaggerapi/swagger-ui/hub.docker.com
基本的なEBの構成はイメージの変更だけでSwagger Codegenと同じでいいはず。環境変数でSwaggerファイルを参照するので、更新されたら念のためアプリケーションサーバの再起動をすれば問題なさそうです。
まとめ
長くなりましたが、これで開発者向けの各種アセットをワンアクションで生成、配備することができるようになりました。次は、コードの更新に合わせてそれを実行する、というプロセスができれば、Serverless Frameworkでマイクロサービスを作る上での基盤というかリファレンスアーキテクチャ的なものができるかな、と。次はその辺りに取り組んでみたいと思います。
Serverless Frameworkを使ってみる
先日、社内システムの一部を再検討するときに、API Gateway + LambdaでServerlessマイクロサービスを選択肢に入れておこうという話をしました。で、言い出しっぺでほっとくのもあれなので、ちょっと自前で検証しておこうというのがこのエントリです。Lambda触ってみたかったですし。
本当だったら開発フローや近隣プロジェクトの開発者へのドキュメントやライブラリ公開まで含めた継続的デプロイまで整備してからリファレンスアーキテクチャ的な形のものを発信したかったんですけど、思ったより検証範囲が大きくなりすぎるので、Serverless frameworkを使ってデプロイしてみたところでエントリ的には一旦区切ります。もう何番煎じかわからないので、細かい設定などは書かずに、やりたいことと参考のリファレンスを整理していこうと思います。
その後の経過については別エントリであげる予定。
先に現状のリポジトリをご査収ください。
Serverless framework is 何?
Serverlessアーキテクチャを作るためのフレームワークとツール類をまとめたものです。AWSだけを対象にしたものではなく、Azureなどの各種クラウド環境に対応しています。LambdaのキックイベントはAPI Gatewayに限らず、S3の更新やCloudWatchあたりを設定することができます。今回私はPythonを使ってプロジェクトを作成しました。AWS関連のエントリではいつも大変お世話になってるクラメソさんのブログを読めば一通り使うことができます。
デプロイ時の定義は serverless.yml
という設定ファイルに記述され、記述に基づいたアプリケーションの構成をCloudFormationで作って後はよしなにしてくれます。Elastic Beanstalkと同じく、後からCloudFormationとかの構成の設定をみて勉強するという使い方もありかもしれません。
ちなみに、デフォルトだとイベント設定されていないので、そのままデプロイしてもAPI GatewayにAPIは作成されません。また、デフォルトのリージョンはus-east-1です。東京リージョンにデプロイするときは serverless.yml
にリージョンをちゃんと指定しておきましょう。
ちなみに、細かい話ですがデプロイしたLambdaファンクションの反映にはコンソールで10〜20秒くらいラグがありました。そんなもんなんですかね?テンプレートで出力されたプロジェクトをテスト的にデプロイしてキックするだけならLambdaの無料枠を超えることもないでしょうから、CloudFormation設定を確保するS3の利用料くらいですみます。
ドキュメント
充実しているのでここから探しましょう。
まずはGuideから読んでいけばいいと思います。最初に動かすまでは、Resource,Variables,Packaging,IAMあたりは必要に応じて読むくらいの心持ちで、大丈夫かと。
ただし、Workflowは読んで置くべきです。
開発時の変更ケースに沿ったデプロイの流れやstageやサービスレベルでのアカウント管理についての注意事項、Serverless Architectureの設計上の勘所あたりが書いてあってとても有用です。
Pythonに関する自分用リンク
まだなんとなくな理解の部分
- stageって何?
- CloudFormationちゃんと使ったことない
- version のピン打ちができるけど、CIとかかけるんだったらやっといた方がいいかも
- Lambdaに置けるエラー処理は結局どうやるのが良さげなのか 関数エラー (Python) - AWS Lambda
- Lambdaファンクションの粒度 Step Functions使ったService層的なものの導入は必要になりそう
シンプルなレスポンスを返すマイクロサービスを作る
で、ここからが本題。実際に開発の場に持ち込むためには以下が足りないんですよ。
- ローカル実行時のDynamoDBの取り扱い
- テスト
どちらもない状態でチーム開発するのはしんどいですよね。というわけでこの辺りを整備してみます。
ローカル実行用にDynamoDBを使いたい
AWS上に作られているDynamoDBのテーブルにアクセスするのは簡単です。公式にもサンプルがあって、その通りに書けばとりあえずはデータのCRUDは試すことができます。
スキーマレスだからserverless.ymlにIDしか定義してなくてデータ突っ込んでるの強引だなあ、とか諸々思うところはあるのですが、それは今議論するところではないのでそっとしておきます。
で、CloudFormationがよしなにテーブル作ってくれたりするのはいいのですが、そのままでは一度でもデプロイしてしまうとローカル実行でもこのDynamoDBテーブルを使うようです。チームで使ったりする場合はちょっと不便。開発者の個別の実行は、AWSが用意しているDynamoDB ローカルを使ってあげるようにしたいですね。
で、見つけたのがこのプラグインです。
で、私のソースは以下のQiita記事を参考に書いているので、 event[isOffline]
を参照してデータソースを切り分けているのですが、
これは別のserverless-offline使う前提の名残です。なぜか私の環境ではpython3.6がunsupportedと出てるのでちょっと保留中です。ぶっちゃけserverless-offline自体はいらないんじゃないか、とも考え中。
Lambdaファンクションにテストを書きたい
初めはdoctestを使って書こうかと思ってたんですが、Lambdaファンクションのハンドラーになる関数だと、DynamoDBとかリソース使い出すとserverless.ymlのコンテキスト渡しづらくなってしんどいんですね。ファンクションの中で適切に分割されたpythonの関数であれば、doctestで十分にかけると思いますが。
というわけで、ハンドラーレベルのテストはServerless Frameworkのローカル実行機能を前提にbats使ってみることにしました。E2Eテストとユニットテストの2段階というイメージです。
リポジトリにもbotsを使ったテストを書いてます。が、一応、テストが書けたけど、シェルスクリプト力の不足でアサーションが非常に弱い状態。誰かまさかり投げて。。。
一旦のまとめ
というわけで、Serverless Frameworkを使ってチームでマイクロサービスを開発する上での方向性とか基盤の整理みたいなものの試行錯誤をしてみました。その一応の成果が先のリポジトリであります。いくつかいけてないところはありますが、そこはこれから洗練させる余地はあると思いますので、まずはこの辺で開発者視点は区切っておこうというのが今回のエントリの主旨です。
で、次はサービスのマネージャ視点になります。サービスは作って終わりではなく、他のサービスやアプリケーションの開発者に提供しなければならないリソースを整備することが必要になりますね、APIドキュメントとかライブラリとか。これらをデプロイに応じて自動で整備をする、というところをやっていきたいと思います。
Swaggerのファイル仕様が不満だったのでRAMLを触って比較してみる
前回、こういうの書きました。
mao-instantlife.hatenablog.com
で、最後に触れたSwaggerの定義ファイルへの不満点。これに悶々としていたところ、隣の席の人にRAMLというのを教えてもらったので比較がてら使ってみました。
RAML is 何?
系統としてはSwaggerと同じく、yaml形式の仕様ファイルから公開向けドキュメントやライブラリ、サーバスタブなどを作るための定義仕様です。仕様のみの提供で、開発環境やコード生成ツールなどはサードパーティやコミュニティで開発されています。
例えばライブラリ生成なんかはこれ。
API Gatewayにデプロイしたいなーというときは、AWSが公式に出しているAPIGateway Importerを使いましょう。
開発環境
デファクトになりそうなのが、API WorkbenchとAPI Designerでした。以下、両者の概要を載せておきます。私はAPI Workbenchを使っています。
API Workbench
一応0.8にも1.0にも対応を謳っていて、Swaggerの公式エディタやAPI Designerと違ってローカルのgitとも連携しやすいのが楽です。
Getting Startedで一通りRAMLの仕様を通り抜けられるところは好感高いです。ただし、まだβ版なので結構バギー。Getting Startedの通りにやろうとするとエラーになる(主にツールの操作で、ramlファイルの編集をすればいいので回避策はある)レベルの完成度。不安定ではありますが、提供されている機能的にも充実しているので使いながら待っていても十分なレベル。
API Designer
Swaggerのエディタと同じくWebベースのデザイナ、エディタです。保存はブラウザのLocal Databaseになります。RAMLはファイルの分割、インクルードができるので作ったらzipでダウンロードしてソース管理に、というワークフローになってちょっと辛いです。また、公式のdockerイメージもないので、その辺は改善して欲しいところ。
Swaggerと比較して嬉しいところ
で、数時間ほどAPI WorkbenchのGetting Startedを通しでやってみながら確認していたわけですが、Swaggerよりも嬉しいファイル仕様がいくつかありました。個人的にはこれがあるだけですごく嬉しい。どれも定義ファイルの記述を短く、シンプルにしてくれるものだと感じました。
リソースタイプ
リソース(URL)ごとにメソッドのパターンをまとめられる仕様です。inputとoutputは型パラメータのように抽象化して指定することが可能なので、再利用できます。だいたいAPIの構成ってリソースの種類ごとに似通う(in/outの型以外)よね、という発想はちゃんと仕様にしておいてくれて嬉しい限り。
resourceTypes: Collection: get: reponses: 200: body: applicaton/json: type: <<item>>[] post: body: application/json: type: <<item>>
上記は GET でリソースのリストを返し、POST で新規作成する、 item
を型パラメータとして持つリソースのパターンを示しています。これをあるリソースに適用するときはこんな感じです。
/newResource # これがURLになる箇所 type: { Collection: {item: newResourceType} } # itemに実際の型定義を指定
トレイト
トレイトはリソース単位ではなくHTTPメソッドの振る舞い(パラメータのとり方とレスポンスの返し方、型)を抽象化することができる機能です。例えば、特定の項目に対するフィルタリングの振る舞いを複数のリソースの同じメソッドで実行する場合、以下のようなトレイトを用意します。
traits: FilterableByColumnKeyword: queryParameter: include: type: string exclude: type: string
これで、特定のキーワードが含まれる場合と含まれない場合のメソッドの振る舞いを定義しました。キーワードはクエリパラメータで指定する形式です。これをあるリソースのGETメソッドに定義する場合は以下です。
/newResource: get: is: [FilterableByColumnKeyword]
サブタイプ
型定義をシンプルにするためにサブタイプの定義仕様もあります。
例えば、Supertypeという基本的な型があって、その派生型で一部属性を共有するSubtypeがあるというケース。
type: Supertype: properties: id: string name: string Subtype: type: Supertype properties: company: string
のような定義で、Supertypeの定義に追加するような派生型が作れます。型のテンプレート的な用途で使うよりは、ちゃんとモデリングして派生の関係を作ってから定義した方がいいと思います。
uses定義
in/outの型やリソースタイプ、トレイトなどを別ファイルに切り出して定義して、それを読み込む機能です。Swaggerの言語仕様にこれが見つからなくてファイルがだだ長くなって「え〜」てな感じだったので、私にとってはこれだけでもRAML圧勝です。
uses: namespace: other_library.raml
のような形式で記述します。
結局やりたいことって
これから先、デプロイをサービス単位にAPI Gateway + LambdaみたいなServerlessにしていくのはデファクトになっていくのかなあ、と思っているのですが、開発者で共有するドキュメントは欲しいです。それに、サービスだけではなく、アプリケーションとして取りまとめるためにはライブラリも必要です。そのために境界はRAMLやSwaggerのようにそれらの生成を前提とした仕様定義を行って、サービスの実装はそれを元にServerless frameworkで行う、みたいな役割分担になってくるのかなあ、と思います。Serverless SPAみたいな構成だとそもそもServerless frameworkだけでいいじゃん、的な結論になると思いますが。
次は、Serverless frameworkを少し触ってからRAMLと繋いでみようかと。
ところで、サービスごとに分割して複数サービスを束ねてアプリケーション作るようなアーキテクチャにすると、トランザクションとか大変そうなんですが、みなさんどうしてるんでしょうね。後、DDDでいうサービス層の一部がフロントエンドでの実装に変わってしまうのではないかとも思ってて、この辺もみなさんどうしてるのか気になりますね。
Swaggerを使ってライブラリ非公開のAPIにライブラリを作って見た
仕事で少し検証をしてみたくなったAPIサービスが見つかりました。
オンデマンドに印刷・発送をするためのAPIサービスなんですが、対応予定言語にJavaがない!REST APIだからどうとでもなるとは言え、フレームワーク的な部分のコードをゴリゴリと書きたくないですよね。本末転倒な楽しさに目覚めてしまう可能性もありますし(そっちかよ)。
というわけで、API仕様も公開されていますし、Swaggerの練習がてら自力でライブラリ生成をして使ってみました。
Swagger is 何?
Open API Specificationの開発者ツールフレームワークで、APIのデザイン、ドキュメンテーション、開発を支援する仕様とツール群を提供しています。Open API SpecificationとはアプリケーションにRESTful APIを作るための書式です。
ツール類は以下の3つで構成されています。
- Swagger Editor -> まあその名の通り、オンラインエディタ(Local Datastoreに保存)かnodeかdockerを選べます
- Swagger Codegen -> Open API Specificationから各種環境用のサーバスタブやライブラリを生成するためのツール
- Swagger UI -> Open API Specificationからインタラクティブな機能を持った開発者向けドキュメントを生成するツールとその開発ドキュメントそのもの
今回サーバスタブは作っていません。
Open API Specification
細かい仕様はここを読みましょう。
定義はymlでもjsonでも書けます。エンドポイントや認証フロー、APIのIn/Outの各種データモデルを定義することができます。
Swaggerに感じる可能性
個人的には、このAPI SpecificationをAPI Gatewayに流してエンドポイントはそっちで管理、実装レイヤはAWS Lambdaという構成にできる方がいいのではないかと思っています。フロントエンドとサービスを切り離して、コンテキストでわけられた各種サービスのエンドポイントをつなぎ合わせて構成に、というとなんかMicroserviceっぽいですね。この構成にする上で、開発者に公開するドキュメントやライブラリは必須なわけですが、設計レベルからのアプローチで設計ドキュメントと実装の一致を測りやすくなっているのは良い感触です。
コンテキストの境界づけをAPIを提供する単位で行うことができ、別のコンテキストの裏口的なアクセスをなるべくブロックすることができます。そういう意味でDDDの各種実装パターンにおける実際のアーキテクチャのリファレンスが少し変わるのではないかと(パターン自体はあまり変わらないのではないかと思っている)。
というわけで使ってみた
swagger.yaml自体は仕様に基づいて書いただけなので、リポジトリをご査収ください。
で、検証している時にいくつか課題があったのでその内容をメモっておきます。
Swagger UIからAPIにアクセスできない
実際に仕様を書いてSwagger UIからアクセスしてみようとすると、こんなエラーが出ました。
Fetch API cannot load https://api.codenberg.io/v1/auth/token. Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://editor.swagger.io' is therefore not allowed access. The response had HTTP status code 404. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
Swagger UIからのアクセスは当然Originではないので、許可されていませんよ、ということ。オンラインエディタで最初に確認しましたが、dockerのコンテナ立ててlocalhostでエディタ立ててもVS Codeの拡張機能使っても同様でした。コンテナはまあ想像していましたが、VS Codeの拡張機能もnode使っているんでしょうね。ちなみに、認証に限らずAPI全般で同じ状態でした。
今回のケースはサーバサイドの問題です。どこまで許可するか、とかセキュリティの問題はありそうですが、少なくとも開発、テスト時に必要なレベルは許可されていないとツール類からアクセスできないのは非常に不便ですね。プルリクエスト投げた時にコメントで追加しています。
生成されるライブラリの認証フロー実装
Javaのライブラリを出力して、検証してみました。で、サンプルとして一緒に出力されるコードが以下のような感じなんですよね。
package sample; import io.swagger.client.*; import io.swagger.client.auth.*; import io.swagger.client.model.*; import io.swagger.client.api.FormatsApi; /** * Created by mao on 2017/06/26. */ public class Application { public static void main(String[] args) { ApiClient defaultClient = Configuration.getDefaultApiClient(); // Configure OAuth2 access token for authorization: codenberg_auth OAuth codenberg_auth = (OAuth) defaultClient.getAuthentication("codenberg_auth"); codenberg_auth.setAccessToken("Access Token"); FormatsApi apiInstance = new FormatsApi(); try { InlineResponse2001 result = apiInstance.getFormats(new Body3()); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling FormatsApi#getFormatById"); e.printStackTrace(); } } }
出力されるライブラリはOAuthの認証フローは実装されず、AccessTokenをセットする前提になっている。認証フローは別のライブラリなどで考慮する出力仕様のようです。他の言語のライブラリ出力ではどうなるかまでは検証していませんが、まあこの辺は知っていればいいだけの話かと。
あと、若干クラス名のつけ方が自動生成っぽいというかアレですね。この辺はもしかしたら定義の仕方次第で回避方法はあるのかも。
ちなみに、ライブラリからのアクセスはうまくいきました。いちいち出力して検証するわけには行かないので、クロスドメインの問題自体はサーバサイドで対応した方がいいですが、回避方法というか検証方法自体は残されている、ということで。
まとめ(というかお願いプリーズ)
自力でライブラリを生成して試せる、というのは非常にありがたいですね。API開発者は各言語用のライブラリを提供する必要はないので、swagger.yamlだけでも公開しておいてくれると非常に助かります。はいはいAPIね、Javaがねーじゃんそっ閉じってことをしなくて済むようになるので。
ちなみに私はSwaggerファイルの仕様というか、長くなりがちなファイル構成に不満がありまくりんぐでしたので、RAMLに乗り換えてみようかと思っております。
「二人で生きていく」という選択
これは、
の24日目のエントリのつもりでした。ちょうどこの時期に少し仕事が忙しくなり、バタバタしてたらそのままスルーしてしまって今に至る、と。長々と寝かせとくのもあれなので、成仏させてあげようと思います。
11/22で結婚してから丸14年、15年目の夫婦になりました。
故あって「二人だけ」
過去エントリ、
mao-instantlife.hatenablog.com
でも触れたことがあるのですが、私たちは「子供を作らないことを選択してから結婚した」夫婦です。その理由については同じく触れるつもりはありませんが、結婚に当たって非常に大きな選択をしたことになります。家族の形がどうあれ、この人と一緒に暮らしていきたかった、と思えた人と出会えたことがまず幸せですね。
二人で生きていく生活で楽な点
- 共働きでなくてもなんとか生活できる
- 家や車や保険がコンパクトでも良い
- お互いの時間の持ち方について合意するのが簡単
生活費の面については、二人で生きていくことを選択した理由にもなっていますが、妻が急に働きに出たりなどがしづらいので、収入については私の一馬力を基本に考えないといけません。その点で家計がコンパクトになっていくのは良いことでした。家も保険も基本的に「後の世代に残す」ことを考えなくていいわけですから。
生活のあり方をコンパクトにしよう、と意識するようにはなりました。
二人で生きていく生活で不便な点
- 初対面の人への説明が面倒
- 交友関係が限定される
最近は、家族の形に関する有形無形の期待感みたいなものはなくなってきた(周りが慣れた?)ので、子供がいないと言っても特に怪訝な目を向けられることもなくなりました。それでも初対面であれば子供のことを聞かれることはあります。質問として無難ですからね、多分天気の次くらいに。「いないんですよ」で察してくれればいいですが、ごく稀に突っ込んだことを聞いてくる人もいるわけですね。この対応は若干疲労感激しいです。あ、でも、他のご家庭のお子さんのことを聞くのが嫌いなわけではないのでそこはご遠慮なく(少なくとも私は)。
交友関係については、場へのアクセスが限定される、というのが正確なところですね。年取ってくると趣味の場も減ってきますし。幸いにして我が家はご近所さんがかなり気さくな方なので、付かず離れずではありますが、全く交友がなくなってしまうということはないです。新しい人と出会うきっかけは着実に減ると思います。
幸いにして、私の方はコミュニティやCoderDojoなどで同世代や家族・ご近所のコンテキストに限らない交友関係を築けていますが、それもできる時とできない時があります。家庭や本業が優先されてしまいますので。
我が家特有の心配事
今年は妻の通院も多くなっていたり、もともと体が強くないのでその点で心配事が多くなったり、と仕事で「家を開ける」ことへの不便さを感じることが多くなってきました。どうしてもリモートワークの利点というのは考えてしまいますね。このご時世でのお仕事、場所を選ばずにできることは多いんだから、世間的にももっとリモートワークが当たり前になってくるといいなあ、とは思います。
飽きない?
全然。妻は楽しい人ですし、いつまで経っても可愛さを失わないですし、月一回のデートも楽しいです。この人だったら飽きないな、と思ったからこそ、二人で生きていく相手としてお互い選んだつもりです。
二人で始まって二人で終わる
ただ、いつかはこの生活も終わります。二人の中でそれはどちらかが死ぬ時だと思っています。
なるべく長く一緒にいて、なるべく同時にが理想だけど、なかなかそうも行かないからなるべく近づくように体を準備していこうとはしています。最近体づくりにこだわってきてるのもそういうこと。長生きにこだわっているわけではありませんが、なるべく病気をせずに、二人で過ごす時間を長くしようね、ということです。後に一人で残る時間が長いほど辛いので、今から「どう終わるのが理想的か」みたいなことは考えるようになっています。以前、「旅のことば」に触れたこともあるんですが、このような準備を少しずつでも進められるといいな、と。
mao-instantlife.hatenablog.com
その時に対してできるアクションを今から取ろうと決意した次第であります。これについては固まってきたらおいおい話できるといいなあ、とか。いつになるかとか言いませんがね。
ともあれ、家族の形とあゆみというのは家族の数だけある、ということです。みんなで幸せになろうぜ。