AWS
S3
swagger-ui

S3の静的WebホスティングでSwagger UIを動作させる


前提条件

この記事ではAWSの環境作成にTerrformを使っています。

リソース名などは適宜読み替えてください。


Swaggerとは?

まとめて頂いている素晴らしいページがありました

https://qiita.com/gcyata/items/342073fa7607fd4082bd

本家サイトはコチラ

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」フォルダを作成してあります


index.html

      // Build a system

const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json", <- 変更
dom_id: '#swagger-ui',
deepLinking: true,


index.html

      // 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 を利用してドキュメントを自動更新するようにします