SwaggerUI를 쉽게 Github Pages에 게시하는 방법

8109 단어 swagger-uigithub-pages

배경



Swagger 초보자이자 Qiita 첫 투고입니다.

Swagger에서 API 문서를 작성하고 Github Pages에서 쉽게 강사하는 방법을 요약합니다.
서버를 가지지 않고 우선 사양서를 보이게 하고 싶을 때에 부디.
(Swagger 초보자로 똑같이 곤란한 사람에게 도움이 된다면…!)

아래의 github에 쓰여진 내용을 조금 변경해 본 느낌입니다.
htps : // 기주 b. 코 m / 페테 r-에 ゔ ㄱ s / 슈 게 r 갓 큐 뵈게 s

조작



0. 준비



Github Pages에서 최종적으로 공개하기 위한 docs 디렉토리와, 일단 샘플로 공개하고 싶은 swagger.yaml 를 준비합니다.

디렉토리 구성
.
└── docs
    └── swagger.yaml

docs/swagger.yaml
swagger: '2.0'
info:
  version: 1.0.0
  title: タイトル
paths:
  '/user/{id}':
    get:
      description: ユーザー情報取得
      parameters:
      - name: id
        in: path
        description: user id
        required: true
        type: number
      responses:
        '200':
          description: 成功
          schema:
            type: object
            properties:
              id:
                type: integer
              username:
                type: string

1. Swagger UI 소스 코드 얻기



Swagger UI Github에서 소스 코드를 가져옵니다.

이번에는 빨리 ZIP로 다운로드합니다.
htps : // 기주 b. 코 m / 슈게 r- 아피 / 슈 게 r- 우이 / 아 r ゔ ぇ / 뭐 r. 지 p

2. dist 디렉토리를 docs에 추가


dist 디렉토리만 사용하므로 ZIP 파일에서 압축을 풀고 docs 다음에 넣습니다.

docs 이하로 확장
$ mkdir docs/dist
$ unzip -d docs/dist -j ~/Downloads/swagger-ui-master.zip */dist/*
  • ~/Downloads/swagger-ui-master.zip 1에서 얻은 ZIP 파일

    • 3. index.html 수정


    docs/dist/index.html Swagger 파일의 경로를 수정하여 제공된 Swagger 파일로 변경합니다.

    docs/dist/index.html의 diff
         window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "https://petstore.swagger.io/v2/swagger.json",
+        url: "../swagger.yaml", // my swagger file
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [

    4. github에 push



    이제 파일 준비가 완료되었으므로 모든 파일을 커밋하고 github에 푸시합니다.

    최종 파일 구성
    .
└── docs
    ├── dist
    │   ├── favicon-16x16.png
    │   ├── favicon-32x32.png
    │   ├── index.html
    │   ├── oauth2-redirect.html
    │   ├── swagger-ui-bundle.js
    │   ├── swagger-ui-bundle.js.map
    │   ├── swagger-ui-standalone-preset.js
    │   ├── swagger-ui-standalone-preset.js.map
    │   ├── swagger-ui.css
    │   ├── swagger-ui.css.map
    │   ├── swagger-ui.js
    │   └── swagger-ui.js.map
    └── swagger.yaml

    5. Github Pages 설정



    Github에 대한 푸시가 완료되면 설정을하고 Github Pages에 게시합니다.
  • Github의 설정 열기
  • "GitHub Pages"의 "Source"를 "master branch/docs folder"로 변경 (기본값은 "None")
  • 바로 옆의 "Save"로 저장

    • 이것으로 Github Pages에 게시가 완료됩니다.

    6. 브라우저로 액세스



    이제 모든 설정이 완료되었으므로 브라우저에서 액세스할 수 있습니다.
    브라우저에서 아래 URL에 액세스하여 표시할 수 있으면 완료됩니다.https://<username>.github.io/<repository>/dist/index.html

    요약



    이제 서버를 사용하지 않고 Swagger 파일을 변경하면 최신 API 사양을 게시할 수 있습니다.

    위의 조작한 Github는 이쪽이 됩니다.
  • Github
  • htps : // 기주 b. 코 m / 보이는 ys / 슈 게 r 호 s 찐 g mp ぇ

  • Github Pages
  • htps : // 보인다 ys. 기주 b. 이오 / 슈게 r- 호 s 찐 g - mp ぇ / ぢ st / 어서 x. HTML


    • 여담



    이제 index.html 는 dist 디렉토리 아래에 있기 때문에 URL에도 dist가 포함되어 버립니다.
    생략하고 싶은 경우는 index.html 를 수정하면 됩니다.
  • index.html를 위의 계층으로 이동
  • docs/dist/index.html => docs/index.html

  • Swagger 파일과 같은 경로 변경 
    • @@ -4,9 +4,9 @@
   <head>
     <meta charset="UTF-8">
     <title>Swagger UI</title>
-    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
-    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
-    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+    <link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" >
+    <link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" />
     <style>
       html
       {
@@ -33,13 +33,13 @@
   <body>
     <div id="swagger-ui"></div>

-    <script src="./swagger-ui-bundle.js"> </script>
-    <script src="./swagger-ui-standalone-preset.js"> </script>
+    <script src="dist/swagger-ui-bundle.js"> </script>
+    <script src="dist/swagger-ui-standalone-preset.js"> </script>
     <script>
     window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "../swagger.yaml", // my swagger file
+        url: "./swagger.yaml", // my swagger file
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [
    favicon 만들기 (HUGO)
    GitHub Pages + Jekyll의 자체 제작 테마에서 빌드 오류가 발생하면

    좋은 웹페이지 즐겨찾기

    개발자 우수 사이트 수집

    개발자가 알아야 할 필수 사이트 100선 추천 우리는 당신을 위해 100개의 자주 사용하는 개발자 학습 사이트를 정리했습니다
    best100-homepage