Swagger API belgelerinden PDF oluşturun

REST web servislerimi görüntülemek için Swagger kullanıcı arayüzünü kullandım ve bir sunucuda barındırdım.

Ancak Swagger'ın bu hizmetine yalnızca belirli bir sunucu üzerinden erişilebilir. Çevrimdışı çalışmak istersem, Swagger kullanıcı arayüzünü kullanarak nasıl statik bir PDF oluşturabileceğimi ve onunla nasıl çalışabileceğimi bilen var mı? Ek olarak, sunucuya erişimi olmayan kişilerle bir PDF paylaşmak kolaydır.

Çok teşekkürler!

Kullanışlı yol: Tarayıcıdan Yazdırma / Önizlemeyi Kullanma

1. Düzenleyici bölmesini gizle
2. Baskı Önizleme (firefox kullandım, diğerleri de iyi)
3. Sayfa düzenini değiştirin ve pdf olarak yazdırın

Https://github.com/springfox/springfox ve https://github.com/RobWin/swagger2markup kullanarak bir yol buldum

Belgeleri uygulamak için Swagger 2'yi kullandı.

Projeyi oluşturduktan sonra ihtiyaç duyulan statik belgeleri (html, pdf vb.) Üretmek için REST projenizi değiştirebilirsiniz.

Bir Java Maven projeniz varsa, aşağıdaki pom snippet'ini kullanabilirsiniz. Bir pdf ve html dokümantasyonu (projenin REST kaynaklarının) oluşturmak için bir dizi eklenti kullanır.

1. rest-api -> swagger.json: swagger-maven-eklentisi
2. swagger.json -> Asciidoc: swagger2markup-maven-eklentisi
3. Asciidoc -> PDF: asciidoctor-maven-eklentisi

Bir eklentinin çıktısı diğerinin girdisi haline geldiğinden, yürütme sırasının önemli olduğunu lütfen unutmayın:

<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 eklentisi, üzerinde çalışılacak bir .adoc dosyasının varlığını varsayar. Swagger2markup eklentisi tarafından oluşturulanları basitçe toplayan bir tane oluşturabilirsiniz:

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

Oluşturulan html belgenizin savaş dosyanızın bir parçası olmasını istiyorsanız, en üst düzeyde bulunduğundan emin olmalısınız - WEB-INF klasöründeki statik dosyalar sunulmayacaktır. Bunu maven-war-eklentisinde yapabilirsiniz:

<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 eklentisi oluşturulan dokümantasyon üzerinde çalışır - bu nedenle, bu eklentilerin daha önceki bir aşamada çalıştırıldığından emin olmalısınız.

Soruna özel olarak hitap eden bir web sitesi https://www.swdoc.org/ oluşturdum . Bu yüzden swagger.json -> Asciidoc, Asciidoc -> pdfcevaplarda önerildiği gibi dönüşümü otomatikleştirir . Bunun faydası, kurulum prosedürlerinden geçmenize gerek olmamasıdır. Url veya yalnızca ham bir json biçiminde bir özellik belgesini kabul eder. Proje C # ile yazılmıştır ve sayfası https://github.com/Irdis/SwDoc

DÜZENLE

Eksik oluşturulan pdf gibi SwDoc ile herhangi bir sorun yaşıyorsanız , json özelliklerinizi burada doğrulamak iyi bir fikir olabilir: http://editor.swagger.io/ .

Ödeme https://mrin9.github.io/RapiPdf özelleştirme ve yerelleştirme özelliği bol özel bir öğesi.

Sorumluluk reddi: Bu paketin yazarıyım

Benim için en kolay çözüm swagger'ı (v2) Postman'a aktarmak ve ardından web görünümüne gitmekti. Orada "tek sütun" görünümünü seçebilir ve tarayıcıyı kullanarak pdf'ye yazdırabilirsiniz. Otomatikleştirilmiş / entegre bir çözüm değil, ancak tek kullanım için iyi. Kağıt genişliğini editor2.swagger.io'dan yazdırmaktan çok daha iyi işler, burada kaydırma çubukları içeriğin bazı kısımlarının gizlenmesine neden olur.