Offline-Dokumentation zu Swagger2: Swagger2-Markup-Code und Plugin-Methode

Internet 2020-04-15 11:09:53 views: null

Verzeichnis

Swagger Artikelzusammenfassung

Einführung in Swagger2Markup

Beschreibung der Projektversion:

swagger2markup Code Weg

Schritt 1: Bearbeiten Sie die Datei pom.xml, um verwandte Abhängigkeiten und Repositorys hinzuzufügen, die verwendet werden müssen

Schritt 2: Schreiben Sie einen Unit-Testfall, um Code zu generieren, der die generierte Dokumentation ausführt

AsciiDoc generieren

Markdown generieren

Konfluenz erzeugen

swagger2markup Plugin Methode

Generieren Sie Asciidoc- oder Markdown-Dokumente

Fügen Sie das swagger2markup-Plugin hinzu

Generieren Sie Asciidoc- oder Markdown-Dokumente

Verwandte Anweisungen

Generieren Sie HTML-Dokumente

Asciidoctor Plugin hinzufügen

Generieren Sie HTML-Dokumente

Generieren Sie PDF-Dokumente

Asciidoctor Plugin hinzufügen

Generieren Sie PDF-Dokumente

Lösen Sie das Problem verstümmelter und leerer PDF-Dateien:

Generieren Sie gleichzeitig HTML- und PDF-Dokumente

Plugin hinzufügen

Generieren Sie gleichzeitig HTML- und PDF-Dokumente

Swagger Artikelzusammenfassung

Einführung in Swagger2Markup

Swagger2Markup ist ein Open Source Projekt auf Github. Das Projekt wird hauptsächlich verwendet, um von Swagger automatisch generierte Dokumente in verschiedene gängige Formate für eine einfache statische Bereitstellung und Verwendung zu konvertieren, z. B.: AsciiDoc, Markdown, Confluence.

Projekthomepage: https://github.com/Swagger2Markup/swagger2markup

Beschreibung der Projektversion:

  • Federstiefel 2.0.x.
  • Prahlerei 2.8.0

swagger2markup Code Weg

Schritt 1: Bearbeiten und pom.xmlHinzufügen zugehöriger Abhängigkeiten und Repositorys, die verwendet werden müssen

<dependency>
	<groupId>io.github.swagger2markup</groupId>
	<artifactId>swagger2markup</artifactId>
	<version>1.3.1</version>
</dependency>

Was von den Komponenten abhängt, sollten diese beiden beachten. In der Offline-Entwicklungsumgebung müssen Sie sie manuell zum lokalen Warehouse hinzufügen

    <dependency>
      <groupId>nl.jworks.markdown_to_asciidoc</groupId>
      <artifactId>markdown_to_asciidoc</artifactId>
      <version>1.0</version>
      <scope>compile</scope>
    </dependency>

    <dependency>
      <groupId>nl.jworks.markdown_to_asciidoc</groupId>
      <artifactId>markdown_to_asciidoc</artifactId>
      <version>1.0</version>
      <scope>compile</scope>
    </dependency>

Schritt 2: Schreiben Sie einen Unit-Testfall, um Code zu generieren, der die generierte Dokumentation ausführt

AsciiDoc generieren

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {

    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/generated"));
    }

}
  • Generiert durch Java-Code: Es müssen nur withMarkupLanguageAttribute geändert werden, um unterschiedliche Formate und toFolderAttribute anzugeben, um unterschiedliche Ausgabeverzeichnisse für die Ergebnisse anzugeben.

Markdown generieren

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/markdown/generated"));

Konfluenz erzeugen

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/confluence/generated"));

Der Inhalt des obigen Codes ist sehr einfach und umreißt einige wichtige Inhalte:

  • MarkupLanguage.ASCIIDOC: Gibt das endgültige Format an, das ausgegeben werden soll. Neben ASCIIDOC gibt es MARKDOWN und CONFLUENCE_MARKUP
  • from(new URL("http://localhost:8080/v2/api-docs"): Geben Sie die Quellkonfiguration zum Generieren statischer Bereitstellungsdokumente an. Diese kann in Form einer URL oder eines String-Typs vorliegen, der der Swagger-Spezifikation entspricht, oder als Stream, der aus einer Datei gelesen wird. Wenn es sich um das aktuelle Swagger-Projekt handelt, verwenden wir den Zugriff auf die lokale Swagger-Schnittstelle. Wenn es sich um die von außen erhaltene Swagger-Dokumentkonfigurationsdatei handelt, können Sie die Zeichenfolge verwenden oder die Datei lesen.
  • toFolder(Paths.get("src/docs/asciidoc/generated"): Geben Sie den spezifischen Verzeichnisspeicherort der endgültig generierten Datei an

Nach dem Ausführen der obigen Testfälle können wir den folgenden Inhalt im src-Verzeichnis des aktuellen Projekts abrufen:

AsciiDoc

src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc
AsciiDoc

Abschlag und Zusammenfluss

src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md

Es ist ersichtlich, dass nach dem Ausführen dieser Methode vier verschiedene statische Dateien generiert werden.

Ausgabe in eine einzelne Datei

Wenn Sie möchten , um die Ergebnisdatei nicht geteilt, so kann sie durch ersetzt werden , toFolder(Paths.get("src/docs/asciidoc/generated")wie toFile(Paths.get("src/docs/asciidoc/generated/all"))das Umwandlungsergebnis ausgegeben wird in einer einzigen Datei, die letztlich auch eine einzelne HTML erzeugen kann.

swagger2markup Plugin Methode

Generieren Sie Asciidoc- oder Markdown-Dokumente

Fügen Sie das swagger2markup-Plugin hinzu

<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.3</version>
                <configuration>
                    <swaggerInput>http://localhost:9210/v2/api-docs</swaggerInput>
                    <!-- 生成asciidoc格式 -->
                    <outputFile>src/docs/asciidoc/generated/all</outputFile>
<!--                    <outputDir>src/docs/asciidoc/generated</outputDir>-->
                    <!-- 生成markdown格式 -->
<!--                    <outputFile>src/docs/markdown/generated/all</outputFile>-->
                    <config>
                        <!-- 生成asciidoc格式 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <!-- 生成markdown格式 -->
<!--                        <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
                        <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
                        <swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
                        <swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>

Generieren Sie Asciidoc- oder Markdown-Dokumente

  • Führen Sie das Projekt aus
  • Führen Sie das swagger2markup-Plugin: maven window: Plugins.swagger2markup unter dem angegebenen Projekt aus

Verwandte Anweisungen

  • swaggerInput : Die von swagger generierte Schnittstelle json- Datendatei .
  • Ausgabe :
    • outputFile: Ausgabe in eine einzelne Datei
    • outputDir: Ausgabe in die angegebene Datei
  • swagger2markup.markupLanguage : Ausgabeformat
  • swagger2markup.outputLanguage : Sprachtyp: wie Chinesisch (ZH), Standard Englisch (EN)
  • swagger2markup.generatedExamplesEnabled : Gibt an, ob HTTP-Anforderungs- und Antwortbeispiele generiert werden sollen, standardmäßig false
  • swagger2markup.inlineSchemaEnabled : Gibt an, ob das Parameter-Inlining aktiviert werden soll
  • swagger2markup.pathsGroupedBy : API-Sortierregeln werden im Allgemeinen nach Tags sortiert

Konfigurationsanweisungen für das Swagger2markup-Plugin

http://swagger2markup.github.io/swagger2markup/1.3.3/#_swagger2markup_properties

Generieren Sie Asciidoc- oder Markdown-Dokumente

Generieren Sie HTML-Dokumente

Asciidoctor Plugin hinzufügen

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    <backend>html5</backend>
                    <attributes>
                        <!--导航栏在左-->
                        <toc>left</toc>
                        <!--显示层级数-->
                        <toclevels>3</toclevels>
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

Generieren Sie HTML-Dokumente

  • Generieren Sie Asciidoc-Dokumente
  • Führen Sie Plugin: Maven Window: Plugins.asciidoctor.asciidoctor: process-asciidoc unter dem angegebenen Projekt aus

Verwandte Anweisungen

  • sourceDirectory : Das Verzeichnis, in dem sich das ASCIDOC-Dokument befindet
  • outputDirectory : HTML-Ausgabeverzeichnis
  • Backend : Typ
Generieren Sie HTML-Dokumente

Generieren Sie PDF-Dokumente

Asciidoctor Plugin hinzufügen

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                  <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                    <backend>pdf</backend>
                </configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                </dependencies>
            </plugin>

Generieren Sie PDF-Dokumente

  • Generieren Sie Asciidoc-Dokumente
  • Führen Sie Plugin: Maven Window: Plugins.asciidoctor.asciidoctor: process-asciidoc unter dem angegebenen Projekt aus

Lösen Sie das Problem verstümmelter und leerer PDF-Dateien:

Das PDF ist verstümmelt und leer

  • Verwenden Sie das JAR-Paket asciidoctorj-pdf im Maven-Repository mit dem Komprimierungswerkzeug, um Folgendes zu öffnen:

    • Geben Sie das Verzeichnis asciidoctorj-pdf-1.5.0-alpha.16.jar \ gems \ asciidoctor-pdf-1.5.0.alpha.16 \ data \ ein
    • Schriftarten: Schriftdateiverzeichnis
    • Themen: Konfigurationsdateiverzeichnis

  • Schriftart herunterladen:

    • Schriftart herunterladen: https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
    • Hinweis: Laden Sie einfach KaiGenGothicCN-Bold.It, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf herunter
    • Legen Sie die Schriftartdatei im Schriftartenverzeichnis ab

  • Konfiguration ändern

    • Geben Sie das Themenverzeichnis ein und ändern Sie die Datei default-theme.yml
    • Ändern Sie die Konfiguration der Schriftartdatei entsprechend dem Attributwert base: font_family: unter font: catalog.
    base:
  font_family: Noto Serif

font:
  catalog:
    Noto Serif:
      normal: KaiGenGothicCN-Regular.ttf
      bold: KaiGenGothicCN-Bold.ttf
      italic: KaiGenGothicCN-Regular-Italic.ttf
      bold_italic: KaiGenGothicCN-Bold-Italic.ttf

Generieren Sie gleichzeitig HTML- und PDF-Dokumente

Plugin hinzufügen

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                  <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                </configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                </dependencies>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                       <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                            <attributes>
                                <!--导航栏在左-->
                                <toc>left</toc>
                                <!--显示层级数-->
                                <toclevels>3</toclevels>
                                <!--自动打数字序号-->
                                <sectnums>true</sectnums>
                            </attributes>
                        </configuration>
                    </execution>
                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                        <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

Generieren Sie gleichzeitig HTML- und PDF-Dokumente

  • Generieren Sie Asciidoc-Dokumente
  • Führen Sie Plugin: Maven Window: Plugins.asciidoctor.asciidoctor: process-asciidoc unter dem angegebenen Projekt aus
  • Erstellen Sie eine Dokumentation (wählen Sie eine der beiden aus): Hinweis: Dieser Schritt dauert etwa sieben oder acht Minuten
    • Führen Sie den Befehl mvn generate-resources aus
    • Verwenden Sie die Idee, um einen Schnellstart einzurichten: Ausführen / Debuggen von Konfigurationen-> Maven-> Befehlszeile: Ressourcen generieren, ausführen

PDFPDF hat verstümmelte und leere Probleme

  • Weitere Informationen finden Sie unter Lösen von Problemen bei der PDF-Generierung

Verwandte Anweisungen

  • Ausführungen : Konfigurationen mehrerer Ausführungsaufgaben
  • execute.id : nicht wiederholbar
  • Sonstiges : Lesen Sie die Anweisungen zum separaten Generieren von HTML und PDF

 

Referenzlink:

http://blog.didispace.com/swagger2markup-markdown-confluence/

Qi Yan Blog Experte
发布了430 篇原创文章 · 获赞 1473 · 访问量 394万+
他的留言板 关注

Ich denke du magst

Origin blog.csdn.net/fly910905/article/details/105504324
Empfohlen
Rangfolge
Täglich
Mehr
2024-05-29(1)
2024-05-28(1)
2024-05-27(1)
2024-05-26(0)
2024-05-25(1)
2024-05-24(13)
2024-05-23(34)
2024-05-22(10)
2024-05-21(34)
2024-05-20(5)

Code World

© 2018 codetd.com