Wygeneruj PDF z dokumentacji Swagger API

93

Użyłem interfejsu użytkownika Swagger do wyświetlenia moich usług sieci Web REST i hostowałem je na serwerze.

Jednak ta usługa Swaggera jest dostępna tylko na określonym serwerze. Jeśli chcę pracować w trybie offline, czy ktoś wie, jak mogę utworzyć statyczny plik PDF za pomocą interfejsu Swagger UI i pracować z nim? Ponadto plik PDF można łatwo udostępnić osobom, które nie mają dostępu do serwera.

Wielkie dzięki!

Aman Mohammed
źródło

Odpowiedzi:

39

Poręczny sposób: Korzystanie z drukowania / podglądu w przeglądarce

  1. Ukryj okienko edytora
  2. Podgląd wydruku (użyłem Firefoxa, inne też dobrze)
  3. Zmień ustawienia strony i wydrukuj do formatu PDF

wprowadź opis obrazu tutaj

Osify
źródło
Prosty! Dokumentacja wychodzi całkiem dobrze.
ShaTin
1
Możesz nawet wybierać między dwoma projektami dokumentacji, o ile są dwie usługi Swagger: editor.swagger.io (nowy) i editor2.swagger.io (poprzedni)!
naXa
Efektywny, ale stratny interfejs bcos swagger HTML UI ma wiele zakładek, dla parametrów metody POST / PUT musisz wybrać między kartą modelu a przykładową kartą wartości, a następnie w wersji wydrukowanej do PDF jedna z nich jest na zawsze ukryta :(
chrisinmtown
To nie zadziałało dla mnie. Każdy punkt końcowy byłby odcinany wraz z końcem strony (bez względu na to, jakiego ustawienia strony użyłem). Następna strona zaczynałaby się wtedy u góry następnego bloku Endpoint. Może coś się zmieniło od czasu napisania tej odpowiedzi.
killa-byte
Nadal widzę, że to działa, może być konieczne dostosowanie marginesu. Wypróbuj na stronie editor.swagger.io
Osify
33

Wymyśliłem sposób, używając https://github.com/springfox/springfox i https://github.com/RobWin/swagger2markup

Użyłem Swaggera 2 do wykonania dokumentacji.

Aman Mohammed
źródło
Cześć, próbuję również wygenerować dokumentację offline za pomocą swagger. Czy jesteś w stanie wygenerować dokumentację swagger?
Sunil Rk
tak, użyłem przykładowych projektów i zintegrowałem w nich kod mojego serwisu internetowego i mogłem wygenerować dokumentację.
Aman Mohammed
1
Czy możesz mi krótko powiedzieć, jak mogę zintegrować mój serwis internetowy z przykładami, o których wspomniałeś powyżej.
Sunil Rk
Projekt swagger2markup wymaga danych wejściowych JSON interfejsu API REST. Jeśli pobierzesz ten projekt gradle i zmienisz plik swagger.json w tym ze szczegółami interfejsu API, a następnie uruchomisz metodę Swagger2MarkupConverterTest JUnit: testSwagger2HtmlConversion, powinna ona wygenerować kod HTML dla Ciebie w folderze build / docs / generated / asciidocAsString projektu. Innymi słowy, są dwie rzeczy. 1) Najpierw wygeneruj format JSON dla swojego interfejsu API REST za pomocą edytora Swagger. 2) Używając tego formatu JSON, możesz użyć projektu swagger2markup do stworzenia samodzielnej dokumentacji HTML API
Aman Mohammed,
22

Możesz zmodyfikować swój projekt REST, aby podczas budowania projektu tworzyć potrzebne dokumenty statyczne (html, pdf itp.).

Jeśli masz projekt Java Maven, możesz użyć poniższego fragmentu kodu. Wykorzystuje szereg wtyczek do generowania pliku PDF i dokumentacji html (zasobów REST projektu).

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

Należy pamiętać, że kolejność wykonywania ma znaczenie, ponieważ wyjście jednej wtyczki staje się wejściem do następnej:

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

Wtyczka asciidoctor zakłada istnienie pliku adoc do pracy. Możesz utworzyć taki, który po prostu zbiera te, które zostały utworzone przez wtyczkę swagger2markup:

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

Jeśli chcesz, aby wygenerowany dokument html stał się częścią twojego pliku wojennego, musisz upewnić się, że znajduje się on na najwyższym poziomie - pliki statyczne w folderze WEB-INF nie będą obsługiwane. Możesz to zrobić za pomocą wtyczki 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>

Wtyczka war działa na wygenerowanej dokumentacji - w związku z tym musisz upewnić się, że te wtyczki zostały wykonane we wcześniejszej fazie.

Herviana
źródło
Cześć @Hervian. Świetna odpowiedź. Jak dotąd przydałaby mi się twoja odpowiedź. Mam dwie klasy o tej samej nazwie, ale w różnych pakietach. Jednak plik swagger.json zawiera definicję tylko dla jednego z nich. Brakuje
drugiego
@Hervian Otrzymałem błędy, dopóki nie wykonałem następujących 1) utworzyłem plik src / main / asciidoc / swagger.adoc z zawartością z góry. 2) dodał te właściwości do klasy procesu POM: <phase.generate-Documentation> </phase.generate-documentation> <generated.asciidoc.directory> $ {project.build.directory} / api-gen </ generated asciidoc.directory> Następnie uruchom "mvn install" i nie widzę błędów mvn ani wtyczek, ale tylko plik overview.adoc zawiera jakąkolwiek zawartość; pliki definitions.adoc i paths.adoc pozostają puste. Proszę o poradę.
chrisinmtown
15

Stworzyłem witrynę internetową https://www.swdoc.org/, która konkretnie odnosi się do problemu. Więc automatyzuje swagger.json -> Asciidoc, Asciidoc -> pdftransformację, jak sugerowano w odpowiedziach. Zaletą tego jest to, że nie musisz przechodzić przez procedury instalacji. Akceptuje dokument specyfikacji w postaci adresu URL lub po prostu surowego pliku json. Projekt jest napisany w C #, a jego strona to https://github.com/Irdis/SwDoc

EDYTOWAĆ

Dobrym pomysłem może być sprawdzenie poprawności specyfikacji json tutaj: http://editor.swagger.io/, jeśli masz jakiekolwiek problemy z SwDoc, takie jak niekompletny generowany plik PDF.

Irdis
źródło
3
thx, yeah, jest całkiem niezły, używam go do moich projektów w pracy. W wolnym czasie myślę o napisaniu kodu wspierającego openapi 3.0.
Irdis,
2
Cała chwała autorom narzędzi, na których się opiera,
ofc
@Irdis Próbowałem użyć linku. Pozwala na parsowanie dokumentu Swagger 2.0, ale dokument, który dostarczam, jest z Open API 3.0 i nie jest w stanie wygenerować dokumentu.
hellowahab
Wypróbowałem swagger 3+ - działa dobrze, ale pokazuje surowy html dla uwag ...
Sasha Bond
To świetne narzędzie! Jeśli kiedykolwiek będziesz miał problemy takie jak ja (takie jak niekompletne generowanie pliku PDF), wklej swój plik json tutaj: editor.swagger.io, aby został automatycznie zweryfikowany, napraw problemy i dobrze będzie wrócić do narzędzia swdoc i wygenerować go poprawnie tym razem.
Thales Valias
9

Do kasy https://mrin9.github.io/RapiPdf niestandardowy element z dużą ilością funkcji dostosowywania i lokalizacji.

Zastrzeżenie: jestem autorem tego pakietu

Mrinmoy
źródło
2
właśnie przetestowałem, ale nie otrzymałem odpowiedzi po kliknięciu „Generuj PDF” ze specyfikacją testu (sklep petrochemiczny)?
imehl
1
@imehl Działa dobrze, gdy testowałem mnie na mac / chrome, mac / firefox, mac / safari i windows / chrome. Działa to tylko w przeglądarce internetowej, która obsługuje komponenty internetowe, takie jak Chrome, Firefox i Safari. Jeśli nadal masz problemy, zaloguj się na Github github.com/mrin9/RapiPdf
Mrinmoy
@Mrinmoy Miałem ten sam problem co imehl, otworzył nową kartę, ale natychmiast się zamknął (ubuntu 18.04 + firefox / chrome oba te same wyniki). Potem zrobiłem to na oknach i zadziałało jak urok. Dziękuję za to narzędzie, jest niesamowite.
Dabux
3
@Dabux nigdy nie testował na Ubuntu, ale jest jedna sytuacja, o której wiem, że ludzie napotykają ten sam problem, co wyjaśniłeś, i to wtedy, gdy masz aktywny program blokujący jako
blokadę
@Mrinmoy masz rację, miałem włączony bloker reklam, to z tego powodu, a nie z powodu systemu operacyjnego.
Dabux
1

Dla mnie najłatwiejszym rozwiązaniem było zaimportowanie swaggera (v2) do Postmana, a następnie przejście do widoku internetowego. Tam możesz wybrać widok „pojedynczej kolumny” i użyć przeglądarki, aby wydrukować do formatu PDF. Nie jest to rozwiązanie zautomatyzowane / zintegrowane, ale dobre do jednorazowego użytku. Obsługuje szerokość papieru znacznie lepiej niż drukowanie z editor2.swagger.io, gdzie paski przewijania powodują ukrywanie części treści.

Szymon
źródło
1
próbowałem tego użyć, ale drukowanie za pośrednictwem strony internetowej dodaje również kilka linków i inne informacje.
hellowahab
Tak, powinienem był o tym wspomnieć. Nie był to problem dla mojego użytku.
Simon