• SpringBoot整合swagger2生成接口文档,并且实现导出功能


    写在前言:前阵子工作涉及到与其他公司进行接口对接,要求要swagger文档,之前没有用过这个,于是写了一下,整理出来

    1、添加swagger依赖

    在项目的pom文件中添加swagger的依赖

    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency>
    

    2、编写swagger的配置类


    代码如下

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //为当前包路径
                    .apis(RequestHandlerSelectors.basePackage("com.anso.data.sync.api.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
        //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //页面标题
                    .title("接口文档")
                    //创建人
                    .contact(new Contact("yedan", null, null))
                    //版本号
                    .version("1.0")
                    //描述
                    .description("数据对接接口文档")
                    .build();
        }
    }
    

    3、swagger在接口上的使用,找到需要生成接口文档的controller下,对class直接注解@Api("文件说明"),在对应的接口上直接用注解@ApiOperation("系统主动推送数据")标明方法的作用,对于需要传参的接口可以使用注解@ApiImplicitParam来对参数进行说明,例如:


    当有多个参数的时候,可以使用注解@ApiImplicitParams
    以上是swagger的使用方式,运行项目可以直接访问 http://localhost:8028/swagger-ui.html,就可以看到对应的接口文档

    4、可以在页面上查看swagger文档后,我们可以继续配置能够导出接口文档,导出html文件的方式,直接在项目的pom文件下添加

    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.6</version>
        <configuration>
            <!-- asciidoc文档输入路径 -->
            <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
            <!-- html文档输出路径 -->
            <outputDirectory>src/docs/asciidoc/html</outputDirectory>
            <backend>html</backend>
            <sourceHighlighter>coderay</sourceHighlighter>
            <!-- html文档格式参数 -->
            <attributes>
                <doctype>book</doctype>
                <toc>left</toc>
                <toclevels>3</toclevels>
                <numbered></numbered>
                <hardbreaks></hardbreaks>
                <sectlinks></sectlinks>
                <sectanchors></sectanchors>
            </attributes>
        </configuration>
    </plugin>
    

    pom文件修改完成后,运行项目,在控制台输入mvn asciidoctor:process-asciidoc 执行,即可在src下可以看到生成的接口文档

    5、同理,用同样的方法可以生成MD格式的,修改pom文件

    <plugin>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup-maven-plugin</artifactId>
        <version>1.3.1</version>
        <configuration>
            <!-- api-docs访问url -->
            <swaggerInput>http://localhost:8028/v2/api-docs</swaggerInput>
            <!-- 生成为单个文档,输出路径 -->
            <outputFile>src/docs/asciidoc/generated/all</outputFile>
            <config>
                <!-- ascii格式文档 -->
                <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
                <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
            </config>
        </configuration>
    </plugin>
    

    pom文件修改完成后,运行项目,在控制台输入mvn swagger2markup:convertSwagger2markup 执行,即可在src下可以看到生成的接口文档
    以上就是swagger2生成接口文档的例子

  • 相关阅读:
    Linux-vim
    [转载]关于eve模拟器上的VPS配置问题
    [转载]cisco 出现%Error opening tftp://255.255.255.255/cisconet.cfg解决方法
    CCNA-NAT
    CCNA-DHCP
    CCNA-ACL
    CCNA-OSPF 配置
    CCNA-OSPF 基础
    枚举的应用
    带索引的遍历
  • 原文地址:https://www.cnblogs.com/yedan/p/13647944.html
Copyright © 2020-2023  润新知