Documentation hors ligne Swagger2: code swagger2markup et méthode du plugin

Internet 2020-04-15 11:10:05 views: null

Annuaire

Résumé de l'article Swagger

Introduction à Swagger2Markup

Description de la version du projet:

swagger2markup code way

Étape 1: Modifiez pom.xml pour ajouter des dépendances et des référentiels associés qui doivent être utilisés

Étape 2: écrire un scénario de test unitaire pour générer du code qui exécute la documentation générée

Générer AsciiDoc

Générer une démarque

Générer de la Confluence

Méthode du plugin swagger2markup

Générer des documents asciidoc ou démarques

Ajouter le plugin swagger2markup

Générer des documents asciidoc ou démarques

Instructions connexes

Générer des documents HTML

Ajouter le plugin asciidoctor

Générer des documents HTML

Générer des documents PDF

Ajouter le plugin asciidoctor

Générer des documents PDF

Résolvez le problème des PDF tronqués et vierges:

Générez des documents HTML et PDF en même temps

Ajouter un plugin

Générez des documents HTML et PDF en même temps

Résumé de l'article Swagger

Introduction à Swagger2Markup

Swagger2Markup est un projet open source sur Github. Le projet est principalement utilisé pour convertir des documents générés automatiquement par Swagger en plusieurs formats populaires pour un déploiement et une utilisation statiques faciles, tels que: AsciiDoc, Markdown, Confluence

Page d'accueil du projet: https://github.com/Swagger2Markup/swagger2markup

Description de la version du projet:

  • botte à ressort 2.0.x
  • swagger 2.8.0

swagger2markup code way

Étape 1: Modifier et pom.xmlajouter des dépendances et des référentiels associés qui doivent être utilisés

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

Cela dépend des composants, ces deux doivent faire attention, dans l'environnement de développement hors ligne, vous devez l'ajouter manuellement à l'entrepôt local

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

Étape 2: écrire un scénario de test unitaire pour générer du code qui exécute la documentation générée

Générer AsciiDoc

@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"));
    }

}
  • Généré par le code Java: il suffit de modifier les withMarkupLanguageattributs pour spécifier différents formats et les toFolderattributs pour spécifier différents répertoires de sortie pour les résultats.

Générer une démarque

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"));

Générer de la Confluence

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"));

Le contenu du code ci-dessus est très simple et décrit quelques contenus clés:

  • MarkupLanguage.ASCIIDOC: Spécifie le format final à imprimer. Outre ASCIIDOC, il existe MARKDOWN et CONFLUENCE_MARKUP
  • from(new URL("http://localhost:8080/v2/api-docs"): Spécifiez la configuration source pour générer des documents de déploiement statiques, qui peuvent prendre la forme d'une URL ou d'un type de chaîne conforme à la spécification Swagger ou d'un flux lu à partir d'un fichier. S'il s'agit du projet Swagger en cours, nous utilisons le moyen d'accéder à l'interface Swagger locale. S'il s'agit du fichier de configuration du document Swagger obtenu de l'extérieur, vous pouvez utiliser la chaîne ou lire le fichier.
  • toFolder(Paths.get("src/docs/asciidoc/generated"): Spécifiez l' emplacement du répertoire spécifique du fichier généré final

Après avoir exécuté les cas de test ci-dessus, nous pouvons obtenir le contenu suivant dans le répertoire src du projet en cours:

AsciiDoc

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

Markdown et Confluence

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

On peut voir que quatre fichiers statiques différents sont générés après l'exécution de cette méthode.

Sortie dans un seul fichier

Si vous ne voulez pas diviser le fichier résultat, il peut être remplacé par toFolder(Paths.get("src/docs/asciidoc/generated")que toFile(Paths.get("src/docs/asciidoc/generated/all"))le résultat de la conversion est sortie vers un seul fichier, qui peut aussi générer à terme un seul html.

Méthode du plugin swagger2markup

Générer des documents asciidoc ou démarques

Ajouter le plugin swagger2markup

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

Générer des documents asciidoc ou démarques

  • Exécutez le projet
  • Exécuter le plugin swagger2markup: fenêtre maven: Plugins.swagger2markup sous le projet spécifié

Instructions connexes

  • swaggerInput : fichier de données json d'interface généré par swagger.
  • Sortie :
    • outputFile: sortie dans un seul fichier
    • outputDir: sortie dans le fichier spécifié
  • swagger2markup.markupLanguage : format de sortie
  • swagger2markup.outputLanguage : type de langue: comme le chinois (ZH), l'anglais par défaut (EN)
  • swagger2markup.generatedExamplesEnabled : spécifie si des exemples de demande et de réponse HTTP doivent être générés
  • swagger2markup.inlineSchemaEnabled : s'il faut activer la mise en ligne des paramètres
  • swagger2markup.pathsGroupedBy : les règles de tri des API sont généralement triées par balises

Instructions de configuration du plugin Swagger2markup

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

Générer des documents asciidoc ou démarques

Générer des documents HTML

Ajouter le plugin asciidoctor

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

Générer des documents HTML

  • Générer des documents asciidoc
  • Exécuter le plugin: fenêtre maven: Plugins.asciidoctor.asciidoctor: process-asciidoc sous le projet spécifié

Instructions connexes

  • sourceDirectory : le répertoire où se trouve le document asciidoc
  • outputDirectory : répertoire de sortie HTML
  • backend : type
Générer des documents HTML

Générer des documents PDF

Ajouter le plugin asciidoctor

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

Générer des documents PDF

  • Générer des documents asciidoc
  • Exécuter le plugin: fenêtre maven: Plugins.asciidoctor.asciidoctor: process-asciidoc sous le projet spécifié

Résolvez le problème des PDF tronqués et vierges:

Le PDF est tronqué et vide

  • Le package jar asciidoctorj-pdf dans le référentiel maven, utilisez l'outil de compression pour ouvrir:

    • Entrez dans le répertoire asciidoctorj-pdf-1.5.0-alpha.16.jar \ gems \ asciidoctor-pdf-1.5.0.alpha.16 \ data \
    • polices: répertoire de fichiers de polices
    • thèmes: répertoire du fichier de configuration

  • Télécharger la police:

    • Téléchargement de polices: https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
    • Remarque: il suffit de télécharger KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf
    • Placez le fichier de police dans le répertoire des polices

  • Modifier la configuration

    • Entrez dans le répertoire des thèmes et modifiez le fichier default-theme.yml
    • Modifiez la configuration du fichier de police correspondant à l'attribut base: font_family: sous 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

Générez des documents HTML et PDF en même temps

Ajouter un plugin

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

Générez des documents HTML et PDF en même temps

  • Générer des documents asciidoc
  • Exécuter le plugin: fenêtre maven: Plugins.asciidoctor.asciidoctor: process-asciidoc sous le projet spécifié
  • Générez de la documentation (choisissez l'une des deux): Remarque: Cette étape prend du temps, environ sept ou huit minutes
    • Exécutez la commande mvn generate-resources
    • Utilisez l'idée pour mettre en place un démarrage rapide: exécuter / déboguer les configurations-> maven-> ligne de commande: générer des ressources, exécuter

PDFPDF a des problèmes brouillés et vierges

  • Reportez-vous à la résolution de problèmes de génération de PDF séparée

Instructions connexes

  • exécutions : configurations de tâches d'exécution multiples
  • execution.id : non répétable
  • Autre : reportez-vous aux instructions pour générer séparément HTML et PDF

 

Lien de référence:

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

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

Je suppose que tu aimes

Origine blog.csdn.net/fly910905/article/details/105504324
conseillé
Classement
du quotidien
Plus
2024-05-18(31)
2024-05-17(4)
2024-05-16(25)
2024-05-15(5)
2024-05-14(11)
2024-05-13(7)
2024-05-12(22)
2024-05-11(31)
2024-05-10(33)
2024-05-09(31)

Code World

© 2018 codetd.com