利用AWS S3部署Swagger api 文件

DDDDD

發佈於軟體開發筆記

2023/10/29閱讀時間約 12 分鐘

最近看到一些網路教學AWS S3可以部署靜態網頁，就想說那不如試試看將local swagger部署上去，之後還可以透過github action 自動部署swagger到s3上，於是花點時間看個影片並搭配chatgpt來實現

相關影片連結可以看這個 Youtube 網址，先了解如何建立一個靜態網頁的設定。

設定S3 服務跟搭建 swagger

第一步你需要先有aws帳號，並前往s3新增一個Buckets

接著創建自己的bucket name ，如果你的名字隨便取，到時候你要綁定網域的話會比較麻煩，而如果你沒有要設定自己的網域的話，可以直接使用s3幫你產生的那組網址就可以訪問了，而這邊因為我會綁定我自己購買的域名，所以先取為test.dale.tw ，方便到時候設定CNAME轉址

而這邊的AWS Region就是你AWS服務地區，直接選日本，因為也沒有台灣可以選XD

接著將bucket 設定對外Public

這邊都不用改直接創建bucket

接著為了方便將上傳的檔案都設成公開訪問for anyone，必須要再調整ACL，到創建bucket底下，選擇permission進入往下滑，會看到Object Ownership

接著將ACL控制打開，接著Save changes

接著創建自己的swagger.yaml檔，這邊推薦一個工具叫stoplight studio，我這邊簡單用了工具先幫我創建一個初版方便測試

創建完畢後將這個檔案上傳到我們s3 bucket 底下，選擇Upload進入

接著上傳資料夾或是單一檔案，我這邊直接將stoplight創建的整包丟上去

接著往下滑可以看到設定permissions的地方，修改一下ACL，把他設成grant public-read access，所有人都可以訪問。

設定好後，S3會產生一串aws可以訪問的網址。這串網址到時候需要放到swagger-ui上

在我們部署靜態網頁時，必須要有一個首頁的html，你可以在本地先創建一個index.html檔案，接著到swagger github網站，將範例code貼上去，接著將紅色框框部分替換成你的swagger文件s3網址

你的index.html文件大概就是長這樣

接著一樣上傳上去s3，最終就會長成下列這樣

接著選擇Properties，來設定靜態網頁

往下滑可以看到Static website hosting這邊來設定靜態網頁

接著enable啟用他，下面會有一個設定index.html跟error document，因為我沒有錯誤頁面，直接填寫index.html即可

設定完後，S3會給我們一串網址來訪問他，這串就是你已經部署上去的靜態網站

接著我們按右鍵在新分頁開啟連結，應該會遇到CROS的問題

Errors Hide Fetch error Failed to fetch https://s3.ap-northeast-1.amazonaws.com/test.dale.tw/reference/swagger.yaml Fetch error Possible cross-origin (CORS) issue? The URL origin (https://s3.ap-northeast-1.amazonaws.com) does not match the page (http://test.dale.tw.s3-website-ap-northeast-1.amazonaws.com). Check the server returns the correct 'Access-Control-Allow-*' headers.

主要是因為我們在index.html設定的swagger url網址是http://s3.ap-northeast-1.amazonaws.com/，而 aws 靜態網頁開頭網址是http://test.dale.tw.s3-website-ap-northeast-1.amazonaws.com/，這時候我們得加上CROS設定。

首先進到Buckets的Permission裡面，往下滑找到CROS設定

接著將下列程式碼貼上去，允許AllowedOrigins記得改上自己的靜態網頁的網址

配置說明可以參考aws s3 這份文件CORS configuration，將靜態網頁的網址加上去

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "http://test.dale.tw.s3-website-ap-northeast-1.amazonaws.com"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]

接著設定完成後複製網址到無痕視窗開啟，應該可以正常看到swagger檔案文件

接著如果要設定特定網域的部分，可以創建一個網域名稱，這邊簡單用之前購買的網域，以Godaddy為例。

在你的網域DNS下新增一組CNAME指向靜態路由的網址，這樣就行了，最後你可以利用http://test.dale.tw 這串網址，來轉址到靜態網站上去。

設定後大約兩分鐘可以嘗試使用http://test.dale.tw來看看是否有成功，正常你應該會再次遇到CROS的問題XDDD..這時候將CORS設定再加上這串網址

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
           "http://test.dale.tw.s3-website-ap-northeast-1.amazonaws.com",
						"http://test.dale.tw"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]

接著再嘗試一次在無痕視窗開啟連結，這樣子就成功了。

這樣子就可以很容易將swagger文件提供給其他人一起看，或是遇到面試時需要設計API給面試官，就能提供網址方便他們透過Swagger-UI觀看你的request and response了。

接著可以試著搭配 github action 來實現自動部署到S3上~

設定Github Action

接著補充說明搭配github action 將swagger.yaml檔案修正完後直接部署到S3 Buckets的自動化，這邊要搭配申請IAM 的金鑰，你會在IAM/USERS/Security credentials 找到Access keys並創建一個，要記得下載JSON檔且要保存好，啊如果不見就....砍掉金鑰重建一個XD，接著將ID跟KEY用來設定GITHUB，放置GITHUB路徑地點如圖。

這邊AWS_ACCESS_KEY_ID 及 AWS_SECRET_ACCESS_KEY 命名會對應到github action 的設定名稱，記得要寫對。

接著建立.github/workflows/xxxx.yaml檔，命名隨便取，但資料夾規則要一致，接著撰寫yaml檔，這邊單純Copy 資料夾下的swagger.yaml，放到對應S3資料夾下，只上傳這份即可。

註：補充說明為什麼可以不用安裝aws cli的工具即可以上傳到aws s3，主要是因為runs-on: ubuntu-latest will have AWS CLI version 1.16.299, and you can do the following:

 - name: Upload to S3
    run: |
      aws s3 cp ./results/ s3://reports/results/ --recursive

可看這篇Issue#4835 文章說明，但其他comment也有提到使用其他方式會比較好~那就看大家要怎麼設定了。

name: Deploy Swagger to AWS S3
on:
	push:
		branches:
			- main

jobs:
	deploy:
		runs-on: ubuntu-latest
		
		steps:
		- name: Checkout code
			uses: actions/checkout@v2
		- name: Upload Swagger to S3
			run: |
				aws s3 cp ./reference/swagger.yaml s3://test.dale.tw/reference/swagger.yaml
				env:
					AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
					AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
					AWS_DEFAULT_REGION: ap-northeast-1

因這邊上傳遇到一個問題，就是在test.dale.tw資料夾下的檔案會因為上傳而將public for anyone關掉，會遇到403 forbidden的問題，IAM跟一些權限設定尚還沒搞懂，故這邊先使用另一個方式處理，針對這個資料夾額外設定Bucket policy，所以這邊我會先把ACL關掉。

首先是先把 block publice access 勾選拿掉

接著把 Object Ownership ACL設定關起來，註：這裡如果Everyone (public access)有打勾read，要先把它移除，才能disabled ACLs。

接著設定這個Bucket policy，根據這個Bucket跟底下的檔案允許可以 "s3:GetObject","s3:ListBucket","s3:PutObject"，上傳檔案後才不會出現403 forbidden的問題，附上設定。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket",
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::test.dale.tw/*",
                "arn:aws:s3:::test.dale.tw"
            ]
        }
    ]
}