Azure Static WebApps에서 swagger-ui API 문서 게시 (인증 있음)

최근 일에서는 php제의 API+nextjs의 프런트 엔드 앱과 같은 구성이 대부분입니다만, 가을 이후에 네이티브 앱의 API만을 개발하는 안건이 진행될 것 같은 느낌입니다. api+프런트의 구성이면 개발자의 수중의 docker 환경에서 개발을 진행하므로 그 안에 swagger-ui의 컨테이너를 넣어 API 사양을 확인할 수 있도록 하고 있습니다만, 네이티브 앱의 개발자에게 API 사양을보기 위해서만 docker 환경을 시작하는 것도 조금 느낄 수 있습니다.

그래서 최근 엄청 좋아하는 Azure Static WebApps에는 기본적으로 인증 기능이 내장되어 있으므로 이 기능을 사용하여 API 사양을 공개할 수 없는지 시도한 결과를 정리했습니다.

swagger-ui 배포용 설정

평상시는 공식의 swagger-ui의 도커 이미지 를 사용하고 있습니다만, 이번은 정적인 사이트로서 구축할 필요가 있으므로, swagger-ui-dist 라고 하는 npm 패키지로 배포되고 있는 swagger-ui의 전달용의 파일을 사용 환경을 만듭니다.

적절한 디렉토리에서 예를 들어 다음과 같이 swagger-ui-dist를 추가하십시오.

$ mkdir swagger-ui-demo
$ cd swagger-ui-demo
$ yarn init
$ yarn add swagger-ui-dist

staticwebapp.config.json 만들기

인증이나 routing의 설정은 staticwebapp.config.json 라는 파일로 지정하므로 다음과 같은 내용으로 작성해 주십시오.
이번에는 공개 대상은 엔지니어이므로 github에서의 인증만 활성화합니다.

{
    "routes": [
        {
            "route": "/",
            "allowedRoles": ["reader"]
        },
        {
            "route": "/login",
            "rewrite": "/.auth/login/github"
        },
        {
            "route": "/.auth/login/twitter",
            "statusCode": 404
        },
        {
            "route": "/logout",
            "redirect": "/.auth/logout"
        }
    ],
    "responseOverrides": {
        "401": {
            "redirect": "/login",
            "statusCode": 302
        }
    }
}  

빌드 설정

bin/build에 다음 내용을 넣고 실행 권한을 둡니다.

#!/bin/sh

if [ ! -d "$SOURCE_DIR/OUT" ];then
    mkdir $SOURCE_DIR/out
fi

curl -OL https://petstore.swagger.io/v2/swagger.json --output swagger.json
cp node_modules/swagger-ui-dist/* $SOURCE_DIR/out/
cp swagger.json $SOURCE_DIR/out/
cp staticwebapp.config.json $SOURCE_DIR/out/
sed -i "s|https://petstore.swagger.io/v2/swagger.json|swagger.json|g" $SOURCE_DIR/out/index.html

$ chmod +x bin/build

이 빌드 스크립트는 샘플용 https://petstore.swagger.io/v2/swagger.json을 다운로드하여 서버의 swagger.json를 참조하도록 구성합니다. 또한 방금 만든 staticwebapp.config.json도 out 디렉터리에 복사했습니다.

실제로 이용하는 경우는, 자신의 서비스용으로 작성한 swagger.json를 out 디렉토리에 카피하도록(듯이) 하면 좋을까 생각합니다.

빌드 스크립트를 실행할 수 있도록package.json에 다음을 추가합니다.

...
  "scripts": {
    "build": "./bin/build"
  },
...  

마지막으로, .gitignore 를 다음의 내용으로 작성해, 모든 파일을 commit 합니다. 이것으로 준비 완료입니다.

.DS_Store
/node_modules
/out

Azure Static WebApps 설정

리포지토리를 준비했으므로 Azure 포털에서 정적 웹 앱을 만듭니다.
참고용으로 스크린샷을 붙여 둡니다만, Build Presets를 Custom로, Output location을 out로 설정하십시오.

사용자 초대

사용자를 등록하려면 Azure Portal의 ロール管理에서 초대 링크를 만듭니다. 이번에는 역할에 reader를 지정합니다.


.

작성된 招待リンク를 사용자에게 보내십시오. 초대 링크에 액세스하면 다음과 같은 인증 화면이 표시됩니다.



로그인이 완료되면 항상 swagger-ui가 표시됩니다.

요약

어떻습니까? Azure Static Web App을 사용하면 매우 쉽게 게시 대상을 제한하고 swagger-ui의 API 사양을 공개 할 수있었습니다.

도움이되면 기쁩니다.

참고 링크

샘플

Azure Static Web Apps 인증 및 승인

구성 파일의 예