Создать PDF из документации Swagger API

93

Я использовал пользовательский интерфейс Swagger для отображения своих веб-сервисов REST и разместил его на сервере.

Однако к этой службе Swagger можно получить доступ только на определенном сервере. Если я хочу работать в автономном режиме, знает ли кто-нибудь, как я могу создать статический PDF-файл с помощью пользовательского интерфейса Swagger и работать с ним? Кроме того, PDF-файлом легко поделиться с людьми, у которых нет доступа к серверу.

Большое спасибо!

Аман Мохаммед
источник

Ответы:

39

Удобный способ: печать / предварительный просмотр через браузер

  1. Скрыть панель редактора
  2. Предварительный просмотр печати (я использовал firefox, другие тоже в порядке)
  3. Измените настройки страницы и распечатайте в pdf

введите описание изображения здесь

Осифы
источник
Просто! Документация выходит неплохо.
ShaTin
1
Вы даже можете выбирать между двумя вариантами оформления документации, если есть две службы Swagger: editor.swagger.io (новый) и editor2.swagger.io (предыдущий)!
naXa
Эффективный, но с потерями bcos swagger HTML UI имеет несколько вкладок, для параметров метода POST / PUT вы должны выбрать между вкладкой модели и вкладкой значений примера, тогда в версии для печати в PDF одна из них навсегда скрыта :(
chrisinmtown
У меня это не сработало. Каждая конечная точка будет отключена с концом страницы (независимо от того, какую настройку страницы я использовал). Следующая страница тогда начнется в верхней части следующего блока Endpoint. Может, что-то изменилось с тех пор, как был написан этот ответ.
killa-byte
Я все еще считаю, что это работоспособно, возможно, вам придется изменить маржу. Попробуйте от editor.swagger.io
Osify
33

Я нашел способ, используя https://github.com/springfox/springfox и https://github.com/RobWin/swagger2markup

Использовал Swagger 2 для реализации документации.

Аман Мохаммед
источник
привет, я также пытаюсь создать офлайн-документацию с помощью swagger. Вы можете создать документацию swagger ??
Sunil Rk
да, я использовал примеры проектов, интегрировал в них код своего веб-сервиса и смог создать документацию.
Аман Мохаммед
1
Не могли бы вы вкратце рассказать мне, как я могу интегрировать свой веб-сервис в примеры, которые вы упомянули выше.
Sunil Rk
Проекту swagger2markup требуется ввод JSON REST API. Если вы загрузите этот проект gradle и измените в нем файл swagger.json с вашими данными API, а затем запустите метод Swagger2MarkupConverterTest JUnit: testSwagger2HtmlConversion, он должен сгенерировать HTML для вас в папке build / docs / generated / asciidocAsString проекта. Другими словами, есть 2 вещи. 1) Сначала сгенерируйте формат JSON для вашего REST API с помощью редактора Swagger. 2) Используя этот формат JSON, вы можете использовать проект swagger2markup для создания отдельной HTML-документации API
Аман Мохаммед
22

Вы можете изменить свой REST-проект, чтобы создавать необходимые статические документы (html, pdf и т. Д.) При создании проекта.

Если у вас есть проект Java Maven, вы можете использовать приведенный ниже фрагмент pom. Он использует серию плагинов для создания документации в формате pdf и html (ресурсов REST проекта).

  1. rest-api -> swagger.json: плагин swagger-maven
  2. swagger.json -> Asciidoc: плагин swagger2markup-maven
  3. Asciidoc -> PDF: плагин 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>

Плагин asciidoctor предполагает наличие файла .adoc для работы. Вы можете создать тот, который просто собирает те, которые были созданы плагином swagger2markup:

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

Если вы хотите, чтобы ваш сгенерированный html-документ стал частью вашего военного файла, вы должны убедиться, что он присутствует на верхнем уровне - статические файлы в папке WEB-INF не будут обслуживаться. Вы можете сделать это в плагине 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>

Плагин war работает со сгенерированной документацией - поэтому вы должны убедиться, что эти плагины были выполнены на более ранней стадии.

Hervian
источник
Привет @Hervian. Отличный ответ. Пока я могу использовать твой ансер. У меня есть два класса с одинаковым именем, но в разных пакетах. Однако swagger.json содержит определение только для одного из них. Другой отсутствует
Эдмонд 02 авг.2016,
@Hervian У меня были ошибки, пока я не сделал следующее: 1) создал файл src / main / asciidoc / swagger.adoc с содержимым сверху. 2) добавил эти свойства в POM: <phase.generate-documentation> process-classes </phase.generate-documentation> <generated.asciidoc.directory> $ {project.build.directory} / api-gen </ generated. asciidoc.directory> Затем запустите «mvn install», и я не вижу ошибок mvn или плагина, но только файл overview.adoc имеет содержимое; файлы definitions.adoc и paths.adoc остаются пустыми. Посоветуйте, пожалуйста.
chrisinmtown
15

Я создал веб-сайт https://www.swdoc.org/, который конкретно посвящен этой проблеме. Таким образом, он автоматизирует swagger.json -> Asciidoc, Asciidoc -> pdfпреобразование, как предлагается в ответах. Преимущество этого в том, что вам не нужно выполнять процедуры установки. Он принимает документ спецификации в виде URL-адреса или просто необработанного json. Проект написан на C # и его страница https://github.com/Irdis/SwDoc

РЕДАКТИРОВАТЬ

Было бы неплохо проверить свои спецификации json здесь: http://editor.swagger.io/, если у вас возникли проблемы с SwDoc, например, неполный PDF-файл.

Irdis
источник
3
спасибо, да, это довольно мило, я использую его для своих рабочих проектов. Я подумываю написать код для поддержки openapi 3.0 в свободное время.
Irdis
2
Вся слава авторам инструментов, на которые он опирается, например
Irdis
@Irdis Я пробовал по ссылке. Он позволяет анализировать документ Swagger 2.0, но предоставленный мной документ имеет Open API 3.0, и он не может сгенерировать документ.
hellowahab
Я попробовал swagger 3+ - работает нормально, хотя для примечаний показывает необработанный html ...
Саша Бонд
Это отличный инструмент! Если у вас когда-либо возникнут проблемы, как у меня (например, PDF-файл создается неполным), вставьте свой json сюда: editor.swagger.io для автоматической проверки, исправьте проблемы, и вам будет хорошо вернуться к инструменту swdoc и сгенерировать его правильно этот раз.
Фалес Валиас,
9

Оформить заказ https://mrin9.github.io/RapiPdf - настраиваемый элемент с множеством функций настройки и локализации.

Отказ от ответственности: я являюсь автором этого пакета

Мринмой
источник
2
только что протестировали, но я не получаю ответа после нажатия кнопки «Создать PDF» с тестовой спецификацией (petstore)?
imehl
1
@imehl Он отлично работает, когда я тестировал себя на mac / chrome, mac / firefox, mac / safari и windows / chrome. Это работает только в веб-браузере, который поддерживает веб-компоненты, такие как Chrome, Firefox и Safari. Если по-прежнему
возникают
@Mrinmoy У меня была та же проблема, что и у imehl, он открыл новую вкладку, но мгновенно закрылся (ubuntu 18.04 + firefox / chrome - тот же результат). Затем я сделал это на окнах, и это сработало как шарм. Спасибо за этот инструмент, он потрясающий.
Dabux
3
@Dabux никогда не тестировался на ubuntu, но я знаю одну ситуацию, когда люди действительно сталкиваются с той же проблемой, что и вы объяснили, и это когда у вас есть активный блокировщик as-blocker или всплывающих окон в браузере
Mrinmoy
@Mrinmoy, вы правы, у меня был включен блокировщик рекламы, это из-за этого, а не из-за ОС.
Dabux
1

Для меня самым простым решением было импортировать swagger (v2) в Postman, а затем перейти в веб-представление. Здесь вы можете выбрать режим просмотра «один столбец» и использовать браузер для печати в формате pdf. Не автоматизированное / интегрированное решение, но подходит для одноразового использования. Он обрабатывает ширину бумаги намного лучше, чем печать из editor2.swagger.io, где полосы прокрутки заставляют части содержимого быть скрытыми.

Саймон
источник
1
попытался использовать это, но распечатка через веб-страницу добавляет несколько ссылок и другую информацию.
hellowahab
Да, я должен был упомянуть об этом. Не было проблемой для моего использования.
Саймон