Documentação offline do Swagger2: código swagger2markup e método de plug-in

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

Diretório

Resumo do artigo do Swagger

Introdução ao Swagger2Markup

Descrição da versão do projeto:

caminho do código swagger2markup

Etapa 1: Edite o pom.xml para adicionar dependências e repositórios relacionados que precisam ser usados

Etapa 2: escreva um caso de teste de unidade para gerar código que executa a documentação gerada

Gerar AsciiDoc

Gerar remarcação

Gerar Confluência

método de plug-in swagger2markup

Gere documentos asciidoc ou markdown

Adicionar plugin swagger2markup

Gere documentos asciidoc ou markdown

Instruções relacionadas

Gere documentos HTML

Adicionar plugin asciidoctor

Gere documentos HTML

Gere documentos PDF

Adicionar plugin asciidoctor

Gere documentos PDF

Resolva o problema de PDF ilegível e em branco:

Gere documentos HTML e PDF ao mesmo tempo

Adicionar plugin

Gere documentos HTML e PDF ao mesmo tempo

Resumo do artigo do Swagger

Introdução ao Swagger2Markup

Swagger2Markup é um projeto de código aberto no Github. O projeto é usado principalmente para converter documentos gerados automaticamente pelo Swagger em vários formatos populares para fácil implantação e uso estático, como: AsciiDoc, Markdown, Confluence.

Página inicial do projeto: https://github.com/Swagger2Markup/swagger2markup

Descrição da versão do projeto:

  • bota de mola 2.0.x
  • swagger 2.8.0

caminho do código swagger2markup

Etapa 1: Editar e pom.xmladicionar dependências e repositórios relacionados que precisam ser usados

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

Dependendo dos componentes, esses dois devem prestar atenção, no ambiente de desenvolvimento offline, é necessário adicioná-lo manualmente ao armazém 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>

Etapa 2: escreva um caso de teste de unidade para gerar código que executa a documentação gerada

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

}
  • Gerado pelo código Java: é necessário modificar apenas withMarkupLanguageatributos para especificar diferentes formatos e toFolderatributos para especificar diferentes diretórios de saída para os resultados.

Gerar remarcação

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

Gerar Confluência

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

O conteúdo do código acima é muito simples e descreve alguns conteúdos principais:

  • MarkupLanguage.ASCIIDOC: Especifica o formato final a ser produzido. Além do ASCIIDOC, existem MARKDOWN e CONFLUENCE_MARKUP
  • from(new URL("http://localhost:8080/v2/api-docs"): Especifique a configuração de origem para gerar documentos de implantação estáticos, que podem estar na forma de um URL ou um tipo de String que esteja em conformidade com a especificação Swagger ou um fluxo lido de um arquivo. Se for o projeto atual do Swagger, usamos o caminho para acessar a interface local do Swagger.Se for o arquivo de configuração de documento do Swagger obtido de fora, você pode usar a string ou ler o arquivo.
  • toFolder(Paths.get("src/docs/asciidoc/generated"): Especifique o local do diretório específico do arquivo final gerado

Depois de executar os casos de teste acima, podemos obter o seguinte conteúdo no diretório src do projeto atual:

AsciiDoc

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

Remarcação e Confluência

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

Pode-se observar que quatro arquivos estáticos diferentes são gerados após a execução desse método.

Saída para um único arquivo

Se você não quer dividir o arquivo de resultado, ele pode ser substituído por toFolder(Paths.get("src/docs/asciidoc/generated")como toFile(Paths.get("src/docs/asciidoc/generated/all"))o resultado da conversão é a saída para um único arquivo, que também pode vir a gerar um único html.

método de plug-in swagger2markup

Gere documentos asciidoc ou markdown

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

Gere documentos asciidoc ou markdown

  • Execute o projeto
  • Execute o swagger2markup plugin: maven window: Plugins.swagger2markup no projeto especificado

Instruções relacionadas

  • swaggerInput : o arquivo de dados json da interface gerado pelo swagger.
  • Saída :
    • outputFile: gera um arquivo único
    • outputDir: saída para o arquivo especificado
  • swagger2markup.markupLanguage : formato de saída
  • swagger2markup.outputLanguage : tipo de idioma: como chinês (ZH), padrão inglês (EN)
  • swagger2markup.generatedExamplesEnabled : especifica se exemplos de solicitação e resposta HTTP devem ser gerados, padrão false
  • swagger2markup.inlineSchemaEnabled : se deseja ativar o parâmetro inlining
  • swagger2markup.pathsGroupedBy : as regras de classificação da API geralmente são classificadas por tags

Instruções de configuração do plugin Swagger2markup

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

Gere documentos asciidoc ou markdown

Gere documentos HTML

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

Gere documentos HTML

  • Gere documentos asciidoc
  • Executar plug-in: janela maven: Plugins.asciidoctor.asciidoctor: process-asciidoc no projeto especificado

Instruções relacionadas

  • sourceDirectory : o diretório em que o documento asciidoc está localizado
  • outputDirectory : diretório de saída HTML
  • back - end : tipo
Gere documentos HTML

Gere documentos PDF

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

Gere documentos PDF

  • Gere documentos asciidoc
  • Executar plug-in: janela maven: Plugins.asciidoctor.asciidoctor: process-asciidoc no projeto especificado

Resolva o problema de PDF ilegível e em branco:

O PDF está ilegível e em branco

  • O pacote jar asciidoctorj-pdf no repositório maven, use a ferramenta de compactação para abrir:

    • Digite o diretório asciidoctorj-pdf-1.5.0-alpha.16.jar \ gems \ asciidoctor-pdf-1.5.0.alpha.16 \ data \
    • fontes: diretório do arquivo de fonte
    • temas: diretório do arquivo de configuração

  • Download da fonte:

    • Download da fonte: https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
    • Nota: Basta fazer o download do KaiGenGothicCN-Bold.It, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf
    • Coloque o arquivo de fonte no diretório de fontes

  • Modificar configuração

    • Digite o diretório de temas e modifique o arquivo default-theme.yml
    • Modifique a configuração do arquivo de fonte correspondente ao valor do atributo base: font_family: em fonte: catálogo.
    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

Gere documentos HTML e PDF ao mesmo tempo

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

Gere documentos HTML e PDF ao mesmo tempo

  • Gere documentos asciidoc
  • Executar plug-in: janela maven: Plugins.asciidoctor.asciidoctor: process-asciidoc no projeto especificado
  • Gere documentação (escolha uma das duas): Nota: Esta etapa leva tempo, cerca de sete ou oito minutos
    • Execute o comando mvn generate-resources
    • Use a idéia para definir um início rápido: configurações de execução / depuração-> maven-> linha de comando: generate-resources, execute

PDFPDF tem problemas ilegíveis e em branco

  • Consulte a solução de problemas de geração de PDF separados

Instruções relacionadas

  • execuções : várias configurações de tarefas de execução
  • Execução.id : Não repetível
  • Outros : consulte as instruções para gerar separadamente HTML e PDF

 

Link de referência:

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

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

Acho que você gosta

Origin blog.csdn.net/fly910905/article/details/105504324
Recomendado
Clasificación
Diario
Más
2024-05-09(31)
2024-05-08(19)
2024-05-07(34)
2024-05-06(4)
2024-05-05(0)
2024-05-04(19)
2024-05-03(7)
2024-05-02(0)
2024-05-01(4)
2024-04-30(34)

Code World

© 2018 codetd.com