Swagger2使用及导出api文档

时间：2025-03-17 14:04:42

swagger2页面上无法传入多文件，解决，引入其他插件

<!--swagger2-->
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId></groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId></groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swagger插件-->
        <dependency>
            <groupId></groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.9.2</version>
        </dependency>

代码

@ApiOperation(value = "附件上传", tags = "附件上传", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    @PostMapping(value = "/upload")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "form", name = "files", value = "文件", allowMultiple = true, dataType = "__file")})
    public void upload(@ApiParam(value = "文件") @RequestPart(value = "files") MultipartFile[] files) {
        try {
            for (MultipartFile file : files) {
                // 使用 BufferedReader 逐行读取文件内容
                BufferedReader reader = new BufferedReader(new InputStreamReader((),"UTF-8"));
                String line;
                while ((line = ()) != null) {
                    // 打印每一行内容
                    ("----"+line);
                }
                ();
            }
        } catch (IOException e) {
            // 处理读取文件时的异常
            ();
        }
    }

页面

http://localhost:8080/

swagger2依赖、导出接口文档

<!--Swagger-UI API文档生产工具-->
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>ncy>
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ;
import ..EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis((""))
                //为有@Api注解的Controller生成API文档
                .apis(())
                //为有@ApiOperation注解的方法生成API文档
                .apis(())
                .paths(())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxxx项目")
                .description("xx接口")
                .contact("xxx")
                .version("1.0")
                .build();
    }
}

第一种控制导出


<!--导出swagger api接口文档     v1-->
<dependency>
            <groupId>.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>paleo-core</artifactId>
            <version>0.10.2</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>vavr</artifactId>
            <version>0.9.2</version>
        </dependency>

<!-- 导出接口文档v1的控制层代码-->

import .;
import .;
import .swagger2markup.Swagger2MarkupConfig;
import .swagger2markup.Swagger2MarkupConverter;
import ..Swagger2MarkupConfigBuilder;
import .;
import ;

import ;
import ;

/**
 * @author: YanZanJie
 * @date: 2021/4/26 8:57
 */
public class SwaggerTo {
    /**
     * 生成AsciiDocs格式文档
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage()
                .withOutputLanguage()
                .withPathsGroupedBy()
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        (new URL("http://127.0.0.1:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(("./docs/asciidoc/generated"));
    }

    /**
     * 生成Markdown格式文档
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage()
                .withOutputLanguage()
                .withPathsGroupedBy()
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        (new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(("./docs/markdown/generated"));
    }
    /**
     * 生成Confluence格式文档
     * @throws Exception
     */
    @Test
    public void generateConfluenceDocs() throws Exception {
        //    输出Confluence使用的格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                .withOutputLanguage()
                .withPathsGroupedBy()
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        (new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(("./docs/confluence/generated"));
    }

    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        //    输出Ascii到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage()
                .withOutputLanguage()
                .withPathsGroupedBy()
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        (new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(("./docs/asciidoc/generated/all"));
    }

    /**
     * 生成Markdown格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage()
                .withOutputLanguage()
                .withPathsGroupedBy()
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        (new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(("./docs/markdown/generated/all"));
    }
}

 swagger2导出第二种方法（html、pdf）

<!-- ********************* swagger导出PDF/HTML所需依赖 START ********************************* -->
        <dependency>
            <groupId>.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>



<!--此插件生成ASCIIDOC-->
            <plugin>
                <groupId>.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <configuration>
                    <!--此处端口一定要是当前项目启动所用的端口-->
                    <swaggerInput>http://localhost:8082/v2/api-docs</swaggerInput>
                    <outputDir>docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                        <>ASCIIDOC</>
                    </config>
                </configuration>
            </plugin>


<!--此插件生成HTML和PDF-->
            <plugin>
                <groupId></groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId></groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.10.1</version>
                    </dependency>
                    <dependency>
                        <groupId></groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>docs/asciidoc/generated</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>docs/asciidoc/html</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

先后运行
mvn asciidoctor:process-asciidoc
mvn generate-resources

第三种方法


        <!--swagger2markup-->
        <dependency>
            <groupId>.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>
        <dependency>
            <groupId></groupId>
            <artifactId>pegdown</artifactId>
            <version>1.4.2</version>
        </dependency>





<plugin>
                <groupId>.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.4</version>
                <dependencies>
                    <dependency>
                        <groupId></groupId>
                        <artifactId>pegdown</artifactId>
                        <version>1.4.2</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <swaggerInput>http://localhost:${}/v2/api-docs</swaggerInput>
                    <!--<outputDir>./docs/asciidoc/generated/all</outputDir>-->
                    <outputFile>./docs/asciidoc/generated/all</outputFile>
                    <config>
                        <>ASCIIDOC</>
                        <>ASCIIDOC</>
                        <>ZH</>
                        <>true</>
                        <>TAGS</>
                    </config>
                </configuration>
            </plugin>
            <!--生成api-->
            <plugin>
                <groupId></groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <!--asciidoc文件目录，请确认文件已经存在-->
                    <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
                    <!---生成html的路径-->
                    <outputDirectory>./docs/asciidoc/html</outputDirectory>
                    <headerFooter>true</headerFooter>
                    <doctype>book</doctype>
                    <backend>html5</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

相关文章