Gradle Swagger Generator Plugin에서 API 문서의 배포 수준 변경

4716 단어 swagger자바gradle
Gradle Swagger Generator Plugin을 사용하여 API 문서를 생성 할 때 초기 상태의 배포 수준을 변경하는 방법을 보여줍니다.

전제



여기에서는 SpringFox 와 같이 소스 코드로부터 API 문서를 생성하는 경우가 아니고, 필기한 YAML 형식의 Swagger 문서로부터 Swagger UI 형식의 API 문서를 생성하는 경우를 상정하고 있습니다.

동작 확인한 소프트웨어의 버전은 다음과 같습니다.
  • Oracle JDK 1.8
  • Gradle 4.10
  • Gradle Swagger Generator Plugin 2.16.0

    • 사용자 정의 전


    doc/api.yaml 에 API 문서가 있는 것으로, Swagger UI 를 생성하기 위한 설정은 대체로 다음과 같이 되어 있을 것입니다.
    plugins {
    id 'org.hidetake.swagger.generator' version '2.16.0'
}

dependencies {
    swaggerUI 'org.webjars:swagger-ui:3.20.3'
}

swaggerSources {
    api {
        inputFile = file('doc/api.yaml')
    }
}

    Swagger UI 형식의 API 문서를 생성하고 브라우저에서 확인하면 모든 엔드포인트가 완전히 배포된 상태가 된다는 것을 알 수 있습니다. 처음에는 이것이 문제가되지 않지만 API의 수가 늘어나면 전체가 파악하기 어렵습니다.
    $ ./gradlew generateSwaggerUI
$ open build/swagger-ui-api/index.html



    사용자 정의 후



    따라서 공식 문서에 따라 설정을 사용자 정의합니다. 플러그인의 설정으로 커스터마이즈 할 수 있는 것은 아니고, 커스터마이즈 끝난 Swagger UI의 HTML 파일을 준비해 플러그인에 짜넣는다는 점이 포인트입니다.
  • Swagger UI 공식 페이지에서 index.html 얻기

  • Gradle Swagger Generator Plugin에 포함될 수 있도록 index.html을 수정하고 설정을 사용자 정의
  • 설정 값 목록 → htps : // 기주 b. 코 m / 슈 게 r- 아피 / 슈 게 r - 우이 / b ぉ b / 뭐 r / 두 cs / 토끼 / 곤후 쿠라 치온. md
  • 여기서 배포 수준 (docExpansion)을 full → list로 변경합니다.
    diff --git a/doc/index.html b/doc/index.html
index 549f5f3..163140a 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -40,6 +40,10 @@
     window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
+        spec: window.swaggerSpec,   // (mandatory) use source of swagger-spec.js
+        validatorUrl: null,         // (mandatory) disable validator
+        docExpansion: 'list',       // expand only the tags
+
         url: "https://petstore.swagger.io/v2/swagger.json",
         dom_id: '#swagger-ui',
         deepLinking: true,

  • 맞춤 index.html로 기본 index.html 덮어쓰기
    diff --git a/build.gradle b/build.gradle
index 0aadabc..286e95b 100644
--- a/build.gradle
+++ b/build.gradle
@@ -49,5 +49,13 @@ jacocoTestReport {
 swaggerSources {
     api {
         inputFile = file('doc/api.yaml')
+        ui {
+            doLast {
+                copy {
+                    from 'doc/index.html'
+                    into outputDir
+                }
+            }
+        }
     }
 }

    • 다시 Swagger UI 형식의 API 문서를 생성하고 브라우저에서 확인하면 이번에는 API 엔드포인트 목록이 제목(태그) 수준에서만 표시되는 것을 볼 수 있습니다.
    $ ./gradlew generateSwaggerUI
$ open build/swagger-ui-api/index.html



    배포 수준 변경에만 국한되지 않고 다른 사용자 지정도 비슷한 단계로 구현할 수 있다고 생각합니다.
    Swagger에서 yaml 데이터를 받은 후 모의 만들기
    Swagger UI를 CircleCI로 호스팅

    좋은 웹페이지 즐겨찾기

    개발자 우수 사이트 수집

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