Tôi đã sử dụng giao diện người dùng Swagger để hiển thị các thiết bị web REST của mình và lưu trữ nó trên một 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ạo tệp PDF tĩnh bằng giao diện người dùng Swagger và làm việc với nó không? Ngoài ra, PDF dễ dàng chia sẻ với những người không có quyền truy cập vào máy chủ.
Cảm ơn nhiều!
Câu trả lời:
Cách tiện dụng : Sử dụng Trình duyệt In / Xem trước
Tôi đã tìm ra cách sử dụng https://github.com/springfox/springfox và https://github.com/RobWin/swagger2markup
Đã sử dụng Swagger 2 để triển khai tài liệu.
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ó một 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 pdf và tài liệu html (trong số các tài nguyên REST của dự án).
Xin lưu ý rằng thứ tự thực thi rất quan trọng, vì đầu ra của một plugin sẽ trở thành đầu vào cho phần 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 tệp .adoc để hoạt động. Bạn có thể tạo một cái mà chỉ cần thu thập những cái đã được tạo bởi 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 mình trở thành một phần của tệp chiến tranh, bạn phải đảm bảo rằng nó có ở 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ể thực hiện việc này trong plugin maven-war-:
<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>
Plugin chiến tranh hoạt động trên tài liệu đã tạo - do đó, bạn phải đảm bảo rằng các plugin đó đã được thực thi trong giai đoạn trước đó.
Tôi đã tạo một trang web https://www.swdoc.org/ để giải quyết vấn đề một cách cụ thể. Vì vậy, nó tự động swagger.json -> Asciidoc, Asciidoc -> pdfchuyển đổi như được gợi ý trong các câu trả lời. Lợi ích của việc này là bạn không cần phải trải qua các thủ tục cài đặt. Nó chấp nhận một tài liệu đặc tả dưới dạng url hoặc chỉ là một json thô. Dự án được viết bằng C # và trang của nó là https://github.com/Irdis/SwDoc
BIÊN TẬP
Bạn nên xác thực thông số kỹ thuật json của mình tại đây: http://editor.swagger.io/ nếu bạn đang gặp bất kỳ sự cố nào với SwDoc, chẳng hạn như pdf được tạo chưa hoàn chỉnh.
Checkout https://mrin9.github.io/RapiPdf một phần tử tùy chỉnh với nhiều tính năng tùy chỉnh và bản địa hóa.
Tuyên bố từ chối trách nhiệm: Tôi là tác giả của gói này
Đối với tôi, giải pháp đơn giản nhất là nhập swagger (v2) vào Postman và sau đó chuyển đến chế độ xem web. Ở đó, bạn có thể chọn chế độ xem "một cột" và sử dụng trình duyệt để in sang pdf. Không phải là giải pháp tự động / tích hợp nhưng tốt để sử dụng một lần. Nó xử lý chiều rộng giấy tốt hơn nhiều so với in từ editor2.swagger.io, nơi thanh cuộn khiến các phần nội dung bị ẩn.