Tạo PDF từ tài liệu API Swagger

Question

Tôi đã sử dụng giao diện người dùng Swagger để hiển thị các dịch vụ web REST của tôi và lưu trữ nó trên máy chủ.

Tuy nhiên, dịch vụ này của Swagger chỉ có thể được truy cập trên một máy chủ cụ thể. Nếu tôi muốn làm việc ngoại tuyến, có ai biết cách tôi có thể tạo một tệp PDF tĩnh bằng cách sử dụng giao diện người dùng Swagger và làm việc với nó không? Ngoài ra, PDF dễ chia sẻ với những người không có quyền truy cập vào máy chủ.

Rất cám ơn!

Answer 1

tôi đã tìm ra một cách sử dụng https://github.com/springfox/springfox và https://github.com/RobWin/swagger2markup

Dùng Swagger 2 để thực hiện tài liệu.

Answer 2

Trong khi giải pháp của Amaan Mohammed có vẻ như nó sẽ hoạt động, có một cách dễ dàng hơn để thực hiện việc này. Hãy xem swagger2markup-cli.

Answer 3

Bạn có thể sửa đổi dự án REST của mình để tạo ra các tài liệu tĩnh cần thiết (html, pdf, v.v.) khi xây dựng dự án.

Nếu bạn có dự án Java Maven, bạn có thể sử dụng đoạn mã pom bên dưới. Nó sử dụng một loạt các plugin để tạo ra một tài liệu pdf và html (của các tài nguyên REST của dự án).

1. còn lại-api -> swagger.json: vênh vang-maven-plugin
2. swagger.json -> Asciidoc: swagger2markup-maven-plugin
3. Asciidoc -> PDF: asciidoctor-maven-plugin

Xin lưu ý rằng thứ tự của các vấn đề thực hiện, kể từ đầu ra của một plugin, trở thành đầu vào cho các tiếp theo:

<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> 

Plugin asciidoctor giả định sự tồn tại của một tệp .adoc để làm việc. Bạn có thể tạo một mà chỉ đơn giản thu thập những cái mà được tạo ra bởi các plugin swagger2markup:

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

Nếu bạn muốn tài liệu html tạo của bạn để trở thành một phần của tập tin chiến tranh của bạn, bạn phải chắc chắn rằng nó hiện diện trên cấp cao nhất - các tệp tĩnh trong thư mục WEB-INF sẽ không được phục vụ. Bạn có thể làm điều này trong maven-chiến-plugin:

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> 

Cuộc chiến hoạt động trên các tài liệu được tạo ra - như vậy, bạn phải chắc chắn rằng những plugin đã được thực hiện trong một giai đoạn trước đó.

Answer 4

cách Handy: Sử dụng trình duyệt In ấn/Preview

1. cửa sổ Hide biên tập
2. Print Preview (tôi đã sử dụng firefox, những người khác cũng tốt)
3. Thay đổi thiết lập trang và in ra pdf