Swagger API 문서에서 PDF 생성


93

Swagger UI를 사용하여 REST 웹 서비스를 표시하고 서버에서 호스팅했습니다.

그러나이 Swagger 서비스는 특정 서버에서만 액세스 할 수 있습니다. 오프라인으로 작업하고 싶은 경우 Swagger UI를 사용하여 정적 PDF를 만들고 작업하는 방법을 아는 사람이 있습니까? 또한 PDF는 서버에 액세스 할 수없는 사람들과 쉽게 공유 할 수 있습니다.

감사합니다!

답변:


39

편리한 방법 : 브라우저 인쇄 / 미리보기 사용

  1. 편집기 창 숨기기
  2. 인쇄 미리보기 (Firefox를 사용했으며 다른 것도 괜찮습니다)
  3. 페이지 설정을 변경하고 pdf로 인쇄

여기에 이미지 설명 입력


단순한! 문서는 아주 잘 나옵니다.
ShaTin

1
Swagger 서비스가 두 개있는 한 두 가지 문서 디자인 중에서 선택할 수도 있습니다 : editor.swagger.io (신규) 및 editor2.swagger.io (이전)!
naXa

효과적이지만 손실이 많은 bcos swagger HTML UI에는 여러 개의 탭이 있습니다. POST / PUT 메소드의 매개 변수의 경우 모델 탭과 예제 값 탭 중에서 선택해야합니다. 그런 다음 PDF로 인쇄 된 버전에서는 그중 하나가 영원히 숨겨져 있습니다 :(
chrisinmtown

이것은 나를 위해 작동하지 않았습니다. 각 끝점은 페이지 끝과 함께 잘립니다 (내가 사용한 페이지 설정에 관계없이). 다음 페이지는 다음 끝점 블록의 맨 위에서 시작됩니다. 이 답변이 작성된 이후로 뭔가 변경되었을 수 있습니다.
killa-byte

여전히 실행 가능하다는 것을 알고 있으며 여백을 조정해야 할 수도 있습니다. editor.swagger.io
Osify

33

https://github.com/springfox/springfoxhttps://github.com/RobWin/swagger2markup을 사용하여 방법을 찾았습니다.

Swagger 2를 사용하여 문서를 구현했습니다.


안녕하세요, 저는 또한 swagger를 사용하여 오프라인 문서를 생성하려고합니다. swagger 문서를 생성 할 수 있습니까?
Sunil Rk

예, 예제 프로젝트를 사용하고 웹 서비스 코드를 통합하여 문서를 생성 할 수있었습니다.
Aman Mohammed

1
위에서 언급 한 예제에 내 웹 서비스를 어떻게 통합 할 수 있는지 간단히 말해 주시겠습니까?
Sunil Rk

swagger2markup 프로젝트에는 REST API의 JSON 입력이 필요합니다. 해당 gradle 프로젝트를 다운로드하고 API 세부 정보와 함께 swagger.json 파일을 변경 한 다음 Swagger2MarkupConverterTest JUnit 메서드 : testSwagger2HtmlConversion을 실행하면 프로젝트의 build / docs / generated / asciidocAsString 폴더에 HTML이 생성됩니다. 즉, 두 가지가 있습니다. 1) 먼저 Swagger 편집기를 사용하여 REST API에 대한 JSON 형식을 생성하십시오. 2) JSON 형식, 당신은 API의 생산 독립형 HTML 문서를 swagger2markup 프로젝트를 사용할 수있는 사용
아만 모하메드

22

REST 프로젝트를 수정하여 프로젝트 빌드시 필요한 정적 문서 (html, pdf 등)를 생성 할 수 있습니다.

Java Maven 프로젝트가있는 경우 아래 pom 스 니펫을 사용할 수 있습니다. 일련의 플러그인을 사용하여 pdf 및 html 문서 (프로젝트의 REST 리소스)를 생성합니다.

  1. rest-api-> swagger.json : swagger-maven-plugin
  2. swagger.json-> Asciidoc : swagger2markup-maven-plugin
  3. Asciidoc-> PDF : asciidoctor-maven-plugin

한 플러그인의 출력이 다음 플러그인의 입력이되므로 실행 순서가 중요합니다.

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.3</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>some.package</locations>
                <basePath>/api</basePath>
                <info>
                    <title>Put your REST service's name here</title>
                    <description>Add some description</description>
                    <version>v1</version>
                </info>
                <swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
                <attachSwaggerArtifact>true</attachSwaggerArtifact>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>${phase.generate-documentation}</phase>
            <!-- fx process-classes phase -->
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>io.github.robwin</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>0.9.3</version>
    <configuration>
        <inputDirectory>${project.build.directory}/api</inputDirectory>
        <outputDirectory>${generated.asciidoc.directory}</outputDirectory>
        <!-- specify location to place asciidoc files -->
        <markupLanguage>asciidoc</markupLanguage>
    </configuration>
    <executions>
        <execution>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-swagger</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.11</version>
        </dependency>
        <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>1.7.21</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
        <!-- You will need to create an .adoc file. This is the input to this plugin -->
        <sourceDocumentName>swagger.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>2</toclevels>
            <generated>${generated.asciidoc.directory}</generated>
            <!-- this path is referenced in swagger.adoc file. The given file will simply 
                point to the previously create adoc files/assemble them. -->
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <outputDirectory>${generated.html.directory}</outputDirectory>
                <!-- specify location to place html file -->
            </configuration>
        </execution>
        <execution>
            <id>asciidoc-to-pdf</id>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${generated.pdf.directory}</outputDirectory>
                <!-- specify location to place pdf file -->
            </configuration>
        </execution>
    </executions>
</plugin>

asciidoctor 플러그인은 작업 할 .adoc 파일이 있다고 가정합니다. swagger2markup 플러그인으로 만든 항목을 단순히 수집하는 항목을 만들 수 있습니다.

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]

생성 된 html 문서가 war 파일의 일부가되도록하려면 해당 문서가 최상위 레벨에 있는지 확인해야합니다. WEB-INF 폴더의 정적 파일은 제공되지 않습니다. maven-war-plugin에서이 작업을 수행 할 수 있습니다.

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <warSourceDirectory>WebContent</warSourceDirectory>
        <failOnMissingWebXml>false</failOnMissingWebXml>
        <webResources>
            <resource>
                <directory>${generated.html.directory}</directory>
            <!-- Add swagger.pdf to WAR file, so as to make it available as static content. -->
            </resource>
            <resource>
                <directory>${generated.pdf.directory}</directory>
            <!-- Add swagger.html to WAR file, so as to make it available as static content. -->
            </resource>
        </webResources>
    </configuration>
</plugin>

war 플러그인은 생성 된 문서에서 작동합니다. 따라서 해당 플러그인이 이전 단계에서 실행되었는지 확인해야합니다.


안녕하세요 @Hervian. 좋은 대답입니다. 지금까지 당신의 anser를 사용할 수 있습니다. 이름은 같지만 패키지가 다른 두 개의 클래스가 있습니다. 그러나 swagger.json에는 그중 하나에 대한 정의 만 포함되어 있습니다. 다른 하나는없는
에드몬드

@Hervian 다음을 수행 할 때까지 오류가 발생했습니다. 1) 위의 내용으로 src / main / asciidoc / swagger.adoc 파일을 만들었습니다. 2) POM에 다음 속성을 추가했습니다. <phase.generate-documentation> process-classes </phase.generate-documentation> <generated.asciidoc.directory> $ {project.build.directory} / api-gen </ generated. asciidoc.directory> 그런 다음 "mvn install"을 실행하면 mvn 또는 플러그인 오류가 표시되지 않지만 overview.adoc 파일에만 내용이 있습니다. definitions.adoc 및 paths.adoc 파일은 비어 있습니다. 조언을 부탁 해요.
chrisinmtown

15

나는 특별히 문제를 해결 하는 웹 사이트 https://www.swdoc.org/ 를 만들었습니다 . 따라서 swagger.json -> Asciidoc, Asciidoc -> pdf답변에서 제안한대로 변환을 자동화 합니다. 이것의 장점은 설치 절차를 거칠 필요가 없다는 것입니다. URL 또는 원시 json 형식의 사양 문서를 허용합니다. 프로젝트는 C #으로 작성되었으며 페이지는 https://github.com/Irdis/SwDoc입니다.

편집하다

pdf가 불완전하게 생성되는 것과 같이 SwDoc에 문제가있는 경우 http://editor.swagger.io/에서 json 사양을 확인하는 것이 좋습니다 .


3
thx, 예, 꽤 좋습니다. 작업 프로젝트에 사용합니다. 여가 시간에 openapi 3.0을 지원하는 코드를 작성하려고합니다.
Irdis

2
그것은 OFC에 의존 도구의 저자에 대한 모든 영광
Irdis

@Irdis 링크를 사용해 보았습니다. Swagger 2.0 문서를 구문 분석 할 수 있지만 내가 제공하는 문서는 Open API 3.0이며 문서를 생성 할 수 없습니다.
hellowahab

나는 swagger 3+를 시도했습니다-잘 작동합니다. 그러나 발언을 위해 원시 html을 보여줍니다 ...
Sasha Bond

이것은 훌륭한 도구입니다! : 내가 가진처럼 (PDF가 불완전 생성되는 것처럼) 혹시 문제가있을 경우, 여기 JSON을 붙여 editor.swagger.io가 자동으로 검증 할 수있는 문제를 해결하고 당신은 swdoc 도구로 돌아가서 제대로 생성하는 것이 좋을 것입니다 이 시간.
Thales Valias

9

체크 아웃 https://mrin9.github.io/RapiPdf 사용자 정의 및 현지화 기능의 많음을 가진 사용자 정의 요소입니다.

면책 조항 : 나는이 패키지의 작성자입니다.


2
방금 테스트했지만 테스트 사양 (petstore)과 함께 "PDF 생성"을 클릭 한 후 응답을받지 못합니까?
imehl

1
@imehl Mac / chrome, mac / firefox, mac / safari 및 windows / chrome에서 나를 테스트했을 때 잘 작동합니다. 이것은 Chrome, Firefox 및 Safari와 같은 웹 구성 요소를 지원하는 웹 브라우저에서만 작동합니다. 여전히 직면 문제는 Github에서 그들을 로그인하면 github.com/mrin9/RapiPdf
Mrinmoy

@Mrinmoy 나는 imehl과 같은 문제가 있었지만 새 탭을 열었지만 즉시 닫혔습니다 (ubuntu 18.04 + firefox / chrome 모두 동일한 결과). 그런 다음 창문에서 해냈고 매력처럼 작동했습니다. 이 도구에 감사드립니다. 굉장합니다.
Dabux

3
@Dabux는 우분투에서 테스트 한 적이 없습니다.하지만 제가 아는 한 가지 상황이 있습니다. 여러분이 설명한 것과 동일한 문제가 발생하는 곳이며 브라우저에 활성 차단기 또는 팝업 차단기가있는 경우입니다
Mrinmoy

@Mrinmoy 당신이 맞습니다, 나는 광고 차단기를 사용했습니다. OS 때문이 아니라 그 때문이었습니다.
Dabux

1

나에게 가장 쉬운 해결책은 swagger (v2)를 Postman으로 가져온 다음 웹보기로 이동하는 것이 었습니다. 여기에서 "단일 열"보기를 선택하고 브라우저를 사용하여 pdf로 인쇄 할 수 있습니다. 자동화 / 통합 솔루션은 아니지만 일회용에 적합합니다. 스크롤바로 인해 콘텐츠의 일부가 숨겨지는 editor2.swagger.io에서 인쇄하는 것보다 용지 너비를 훨씬 더 잘 처리합니다.


1
이것을 사용해 보았지만 웹 페이지를 통한 인쇄는 여러 링크와 기타 정보도 추가합니다.
hellowahab

네, 말씀 드렸어야 했어요. 내 사용에 문제가되지 않았습니다.
Simon
당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.