Swagger API 문서에서 PDF 생성

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

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

감사합니다!

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

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

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

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

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 플러그인은 생성 된 문서에서 작동합니다. 따라서 해당 플러그인이 이전 단계에서 실행되었는지 확인해야합니다.

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

편집하다

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

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

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

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