前提条件
この記事ではAWSの環境作成にTerrformを使っています。
リソース名などは適宜読み替えてください。
Swaggerとは?
まとめて頂いている素晴らしいページがありました
本家サイトはコチラ
https://swagger.io/
今回のゴール
今回はその中のSwagger UI(Swagger-Specを読み込んで、HTML形式でドキュメントを生成するためのツール)をWebホスティングで構築したいと思います。
本来は Swagger UI が動作するサーバーを用意する感じみたいなのですが、実業務で利用する際にメンバーが簡単に使えないと利用されないと思い、利用側は裏側を意識せず利用することを目的としています。
構築
AWSの構築は terraformで作成します。
terraform で静的ウェブサイトホスティング用に S3 バケットを作成
※アクセスできるIP許可設定は設定してください。
variable "website_bucket_name_apidoc_com" {
default = "apidoc.com"
}
# AWS S3 bucket for static hosting
resource "aws_s3_bucket" "apidoc_com" {
bucket = "${terraform.workspace}.${var.website_bucket_name_apidoc_com}"
acl = "private"
tags {
Environment = "${terraform.workspace}"
}
policy = <<EOF
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "PublicReadForGetBucketObjects",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::${terraform.workspace}.${var.website_bucket_name_apidoc_com}/*",
"Condition": {
"IpAddress": {
"aws:SourceIp": [
<<許可するIPアドレス群>>
]
}
}
}
]
}
EOF
website {
index_document = "index.html"
error_document = "error.html"
}
}
ドキュメントファイル
公式がgithubに提供しています。
https://github.com/swagger-api/swagger-ui
dist フォルダをS3に展開します。
展開する際にindex.htmlだけ少し修正します。
※また SwaggerJsonの展開先として、「json/v2」フォルダを作成してあります
// Build a system
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json", <- 変更
dom_id: '#swagger-ui',
deepLinking: true,
↓
// Build a system
const ui = SwaggerUIBundle({
url: "http://apidoc.com/json/v2/swagger.json",
dom_id: '#swagger-ui',
deepLinking: true,
S3にアップロード後、 http://apidoc.com/json/v2/swagger.json にアクセスすることでドキュメントを閲覧することができます。
次回の内容
完全なゴールを目指すため、CodeCommit と CodePipeline を利用してドキュメントを自動更新するようにします