2015-05-13 47 views
44

से PDF उत्पन्न मैं स्वैगर यूआई का इस्तेमाल किया है मेरी बाकी webservices प्रदर्शित करने और एक सर्वर पर होस्ट किया गया है।स्वैगर API दस्तावेज़

हालांकि स्वैगर की यह सेवा केवल एक विशेष सर्वर पर पहुँचा जा सकता है। अगर मैं ऑफ़लाइन काम करना चाहता हूँ, किसी को भी पता है कि कैसे मैं एक स्थिर पीडीएफ स्वैगर यूआई और इसके साथ काम का उपयोग कर बना सकते हैं? इसके अतिरिक्त पीडीएफ उन लोगों के साथ साझा करना आसान है जिनके पास सर्वर तक पहुंच नहीं है।

बहुत धन्यवाद!

उत्तर

18

मैं एक तरह से https://github.com/springfox/springfox और https://github.com/RobWin/swagger2markup

प्रलेखन लागू करने के लिए स्वैगर 2 प्रयुक्त का उपयोग कर पता लगा।

+0

हाय, मैं भी कोशिश कर रहा हूं swagger का उपयोग कर ऑफ़लाइन दस्तावेज उत्पन्न करने के लिए। क्या आप swagger दस्तावेज उत्पन्न करने में सक्षम हैं ?? –

+0

हां, मैंने उदाहरण परियोजनाओं का उपयोग किया और मेरे webservice कोड को एकीकृत किया और दस्तावेज उत्पन्न करने में सक्षम था। –

+0

क्या आप कृपया मुझे संक्षेप में बता सकते हैं, मैं ऊपर बताए गए उदाहरणों के लिए अपनी वेब सेवा को कैसे एकीकृत कर सकता हूं। –

3

अमान मोहम्मद के समाधान लगता है कि यह काम करते हैं, वहाँ यह करने के लिए एक आसान तरीका है। swagger2markup-cli पर एक नज़र डालें।

12

आप अपने बाकी प्रोजेक्ट को संशोधित इतनी के रूप में परियोजना के निर्माण पर जरूरत स्थिर दस्तावेजों (एचटीएमएल, पीडीएफ आदि) का उत्पादन कर सकते हैं।

आप एक जावा Maven परियोजना आप नीचे दिए गए पोम स्निपेट का उपयोग कर सकते हैं। यह एक पीडीएफ और एक एचटीएमएल दस्तावेज (परियोजना के आरईएसटी संसाधनों) उत्पन्न करने के लिए प्लगइन की एक श्रृंखला का उपयोग करता है।

  1. बाकी-api -> swagger.json: अकड़-Maven-प्लगइन
  2. swagger.json -> Asciidoc: swagger2markup-Maven-प्लगइन
  3. Asciidoc -> पीडीएफ: asciidoctor-Maven-प्लगइन

कृपया ध्यान रखें कि निष्पादन का क्रम महत्वपूर्ण, एक प्लगइन के उत्पादन के बाद से, अगले करने के लिए इनपुट हो जाता है:

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

एसिडिक्टर प्लगइन काम करने के लिए एक .adoc फ़ाइल के अस्तित्व को मानता है। आप एक है कि बस जो कि swagger2markup प्लगइन द्वारा बनाया गया था एकत्र करता है बना सकते हैं:

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

आप अपने उत्पन्न एचटीएमएल दस्तावेज़ अपने युद्ध फ़ाइल का हिस्सा बनने के लिए आप यकीन है कि यह पर मौजूद है करना है चाहते हैं शीर्ष स्तर - वेब-आईएनएफ फ़ोल्डर में स्थिर फाइलों की सेवा नहीं की जाएगी। आप Maven युद्ध प्लगइन में ऐसा कर सकते हैं:

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

युद्ध प्लगइन उत्पन्न प्रलेखन पर काम करता है - जैसे, आप यह सुनिश्चित करें कि उन प्लगइन्स एक पहले चरण में मार दिया करना चाहिए।

+0

हाय @ हार्वियन के स्टैंडअलोन एचटीएमएल दस्तावेज का उत्पादन करने के लिए swagger2markup प्रोजेक्ट का उपयोग कर सकते हैं। बहुत बढ़िया जवाब। मैं अब तक आपके उत्तरदाता का उपयोग कर सकता हूं। मेरे पास एक ही नाम के साथ दो वर्ग हैं लेकिन विभिन्न पैकेजों में। हालांकि swagger.json उनमें से केवल एक के लिए परिभाषा है। दूसरे में – edmond

12

आसान तरीका: ब्राउज़र प्रिंटिंग/पूर्वावलोकन का उपयोग करके

  1. संपादक छुपाएं फलक
  2. मुद्रण पूर्वावलोकन
  3. बदलें अपनी पृष्ठ सेटअप (मैं फ़ायरफ़ॉक्स, दूसरों को भी ठीक करता था) और पीडीएफ
  4. से प्रिंट

enter image description here

+0

सरल है! दस्तावेज़ीकरण काफी अच्छी तरह से आता है। – ShaTin

+1

जब तक दो स्वैगर सेवाएं हैं, तब तक आप दो दस्तावेज़ डिज़ाइनों के बीच भी चयन कर सकते हैं: https://editor.swagger.io/ (new) और http://editor2.swagger.io (पिछला)! – naXa

संबंधित मुद्दे