मैंने स्वैगर UI का उपयोग अपने REST वेबसर्विस को दिखाने और सर्वर पर होस्ट करने के लिए किया है।
हालांकि स्वैगर की इस सेवा को केवल एक विशेष सर्वर पर ही एक्सेस किया जा सकता है। अगर मैं ऑफ़लाइन काम करना चाहता हूं, तो क्या कोई जानता है कि मैं स्वैगर यूआई का उपयोग करके एक स्थिर पीडीएफ कैसे बना सकता हूं और इसके साथ काम कर सकता हूं? इसके अतिरिक्त एक पीडीएफ उन लोगों के साथ साझा करना आसान है जिनके पास सर्वर तक पहुंच नहीं है।
बहुत धन्यवाद!
जवाबों:
आसान तरीका: ब्राउज़र प्रिंटिंग / पूर्वावलोकन का उपयोग करना
मैंने https://github.com/springfox/springfox और https://github.com/RobWin/swagger2markup का उपयोग करके एक तरीका निकाला
प्रलेखन को लागू करने के लिए स्वैगर 2 का उपयोग किया।
आप अपनी REST परियोजना को संशोधित कर सकते हैं, ताकि परियोजना के निर्माण पर आवश्यक स्थैतिक दस्तावेजों (html, pdf आदि) का उत्पादन कर सकें।
यदि आपके पास जावा मावेन परियोजना है तो आप नीचे पोम स्निपेट का उपयोग कर सकते हैं। यह पीडीएफ़ और HTML डॉक्यूमेंट बनाने के लिए प्लगइन्स की एक श्रृंखला का उपयोग करता है (परियोजना के रीस्ट संसाधनों में)।
कृपया ध्यान रखें कि निष्पादन का क्रम, एक प्लगइन के आउटपुट के बाद से, अगले इनपुट बन जाता है:
<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 डॉक्यूमेंट आपकी युद्ध फाइल का हिस्सा बन जाए, तो आपको यह सुनिश्चित करना होगा कि यह शीर्ष स्तर पर मौजूद है - WEB-INF फ़ोल्डर में स्टैटिक फाइल्स को सर्व नहीं किया जाएगा। आप इसे मावेन-युद्ध-प्लगइन में कर सकते हैं:
<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>
युद्ध प्लगइन उत्पन्न प्रलेखन पर काम करता है - जैसे, आपको यह सुनिश्चित करना होगा कि उन प्लगइन्स को पहले चरण में निष्पादित किया गया है।
मैंने एक वेब साइट बनाई https://www.swdoc.org/ जो विशेष रूप से समस्या का समाधान करती है। तो यह swagger.json -> Asciidoc, Asciidoc -> pdfजवाबों में सुझाए अनुसार परिवर्तन को स्वचालित करता है। इसका लाभ यह है कि आपको इंस्टॉलेशन प्रक्रियाओं से गुजरने की आवश्यकता नहीं है। यह url के रूप में या सिर्फ एक कच्चे जोंस के रूप में एक विशेष दस्तावेज को स्वीकार करता है। प्रोजेक्ट C # में लिखा गया है और इसका पेज https://github.com/Irdis/SwDoc है
संपादित करें
यहाँ अपने json स्पेक्स को मान्य करना एक अच्छा विचार हो सकता है: http://editor.swagger.io/ यदि आपको SwDoc से कोई समस्या हो रही है, जैसे कि pdf अधूरी उत्पन्न की जा रही है।
चेकआउट https://mrin9.github.io/RapiPdf बहुत सारे अनुकूलन और स्थानीयकरण सुविधा के साथ एक कस्टम तत्व।
डिस्क्लेमर: मैं इस पैकेज का लेखक हूं
मेरे लिए सबसे आसान उपाय पोस्टमैन में स्वैगर (v2) आयात करना और फिर वेब दृश्य पर जाना था। वहां आप "सिंगल कॉलम" दृश्य चुन सकते हैं और ब्राउज़र को पीडीएफ में प्रिंट करने के लिए उपयोग कर सकते हैं। एक स्वचालित / एकीकृत समाधान नहीं है, लेकिन एकल-उपयोग के लिए अच्छा है। यह Editor2.swagger.io से छपाई की तुलना में कागज-चौड़ाई को बहुत बेहतर तरीके से संभालता है, जहां स्क्रॉलबार सामग्री के कुछ हिस्सों को छिपाते हैं।