Swagger UI(feat. keycloak Open API)

 

1. Swagger UI

Swagger UI라는 도커 이미지가 제공된다!

https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/installation.md

 

 

docker run -p 80:8080 swaggerapi/swagger-ui

 

 

해당 도커 컨테이너를 실행하고, localhost로 접속하여 위 쪽 입력창에 .json 파일의 웹 주소를 입력하면 API를 사용할 수 있는 Swagger 문서가 생성된다.

 

 

 

나는 keycloak의 REST API를 확인해보기 위해서 keycloak의 OPEN API 문서의 주소를 붙여넣었다.

https://www.keycloak.org/docs-api/latest/rest-api/openapi.json

 

 

 

2. Keycloak REST API 테스트

 

2.1 OPEN API의 servers, securtyScheme

keycloak REST API 테스트를 위해서는 service account role의 client를 통한 로그인이 필요하다. 이를 위해서 OPEN API 문서에 아래 항목들을 추가해야한다. 해당 내용은 아래 Swagger document에 적혀있다.

https://swagger.io/docs/specification/v3_0/authentication/?sbsearch=securityscheme

Authentication

 

우선 keycloak에서 제공하는 .yaml 형식의 OPEN API 문서를 다운로드 받는다.

 

해당 문서에는 servers, securityScheme 항목이 없다. 이를 채워넣어주면 된다. keycloak은 localhost:8080, swagger-ui는 localhost:8081에서 실행할 것이다.두 컨테이너의 네트워크가 다르면 안된다. 테스트에서는 딱 컨테이너 1개씩만 실행하고 네트워크는 별도로 설정하지 않도록 하여 default bridge 네트워크만 사용하도록 한다.

---

openapi: 3.0.3

info:

title: Keycloak Admin REST API

description: This is a REST API reference for the Keycloak Admin REST API.

version: "1.0"

servers:

- url: http://localhost:8080

 

 

 

9628번째 줄 정도에 있다. IDE를 통해 components: 라는 항목을 검색하여 해당 항목 하위에 securityScheme 항목을 작성해주어야 한다. security 항목도 bearerAuth로 작성해준다.

security:

- bearerAuth: []

components:

securitySchemes:

bearerAuth: # arbitrary name for the security scheme

type: http

scheme: bearer

bearerFormat: JWT # optional, arbitrary value for documentation purposes

schemas:

 

 

2.2 Swagger-ui 실행

아래 명령어로 실행한다. 실행할 OPEN API 문서가 있는 디렉토리에서 실행하면 된다.

 

docker run -p 8081:8080 -e SWAGGER_JSON=/docs/kc.yaml -v $(pwd)/kc-restapi.yaml:/docs/kc.yaml swaggerapi/swagger-ui

 

로컬 PC의 8081 포트를 Swagger-ui 컨테이너의 8080에 매핑한다. 그리고 SWAGGER_JSON 옵션으로 Swagger-ui 컨테이너 내부에 있는(있을) OPEN API 문서의 위치를 지정한다.

 

-v 볼륨 매핑을 통해서 로컬 pc의 현재위치/kc-restapi.yaml (내 로컬의 yaml 파일) 을 컨테이너의 /docs/kc.yaml로 바인딩 해준다.

 

 

 

2.3 Keycloak에서 처리

 

어떤 realm에서 client를 통해 정보들을 조회할려면 Service account role들이 필요하다. realm에 client를 만들고, 아래와 같이 service account roles를 추가한다. 또한 CORS 정책에 막히지 않기 위해서 Web Origins에 스웨거의 주소인 http://localhost:8081을 등록해주어야한다.

 

 

그리고 service account roles에 admin REST API로 접근할 수 있도록 모든 role들을 추가해준다.

 

 

2.4 Swagger에서 호출

 

service account로 접근할 것이기 때문에, 로그인 및 access token이 필요하다. 아래와 같이 postman을 통해서 token을 요청했다.

 

그리고 access_token을 복사하여 로그인한다.

 

 

그리고 요청을 날려본다. 나의 경우 realm내 client 목록을 호출하는 API에 요청했다.

 

응답은 아래와 같이 client 정보 목록이 나오는 것을 확인할 수 있었다.