欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

swagger导出接口文档

程序员文章站 2022-07-02 20:57:17
...

最近工作上需要用Swagger导出接口文档
经过查找资料总结了一下:

Swagger简介

1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
简单来说,Swagger是一个帮助开发人员编写接口文档的工具,它可以帮你自动生成接口文档。

Swagger使用

项目中使用Swagger有两种方法
1.**

使用第三方依赖

**

(1) pom.xml文件引入依赖:

<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>

(2)在Spring Boot项目的启动类上添加@EnableSwagger2注解,api方法中添加注解。

2.使用官方依赖

① pom.xml文件引入依赖:

io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0

② 编写Swagger控制类

注意:swagger scan base package,这是扫描注解的配置,即你的API接口位置。需要修改为实际项目的Api位置
③ 在Spring Boot项目的启动类上添加@EnableSwagger2注解,api方法中添加注解。

3访问api doc 路由
项目启动后可以打开浏览器访问:
页面图下:
swagger导出接口文档
访问地址为:http://localhost:8080/swagger-ui.html(端口号应改为实际项目端口号)
注:生成静态文档使用的url为红色框中url,而不是swagger-ui.html
图中红色框地址是默认路由,访问路由可以进行配置:
application.yml中声明:
springfox.documentation.swagger.v2.path: /api-docs
/api-docs就是自定义的路由,可以自定义
生成的接口文档可以在线进行接口测试
*需要注意的是当前日志文档是动态的,项目启动才可以以网页方式访问
4

Swagger常用Api

1、api标记
Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:

@Api(value = “/user”, description = “Operations about user”)

2、ApiOperation标记
ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

@ApiOperation(
value = “Find purchase order by ID”,
notes = “For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions”,
response = Order,
tags = {“Pet Store”})

3、ApiParam标记
ApiParam请求属性,使用方式:

public ResponseEntity createUser(@RequestBody @ApiParam(value = “Created user object”, required = true) User user)
1
4、ApiResponse
ApiResponse:响应配置,使用方式:
@ApiResponse(code = 400, message = “Invalid user supplied”)
5、ApiResponses
ApiResponses:响应集配置,使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = “Invalid Order”) })

6、ResponseHeader
响应头设置,使用方法
@ResponseHeader(name=“head1”,description=“response head conf”)

Swagger生成静态接口文档

上面生成的接口文档是动态的,可以方便开发人员进行接口测试,如果想要生成静态文档还需要额外的配置。
生成静态文档也有两种方法
1.编写java代码生成
2.Maven插件完成
编写java代码生成:

1)Pom.xml文件中添加依赖

<dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <dependency>
            <groupId>ch.netzwerg</groupId>
            <artifactId>paleo-core</artifactId>
            <version>0.10.2</version>
        </dependency>
        <dependency>
            <groupId>io.vavr</groupId>
            <artifactId>vavr</artifactId>
            <version>0.9.2</version>
        </dependency>

注:Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。
2)编写单元测试用例生成文档(执行test测试方法生成文档)

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
 
import java.net.URL;
import java.nio.file.Paths;
 
 
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class SwaggerTo {
 
    /**
     * 生成AsciiDocs格式文档
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
 
        Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));
    }
 
    /**
     * 生成Markdown格式文档
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
 
        Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
    } 
    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        //    输出Ascii到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
 
        Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }
 
    /**
     * 生成Markdown格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
 
        Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/markdown/generated/all"));
    }
}

说明:
· MarkupLanguage.ASCIIDOC:指定了要输出的最终格式。除了ASCIIDOC之外,还有MARKDOWN和CONFLUENCE_MARKUP
· from(new URL(“http://localhost:8080/v2/api-docs”):指定了生成静态部署文档的源头配置,可以是这样的URL形式,也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目,我们通过使用访问本地Swagger接口的方式,如果是从外部获取的Swagger文档配置文件,就可以通过字符串或读文件的方式
· toFolder(Paths.get(“src/docs/asciidoc/generated”):指定最终生成文件的具体目录位置

swagger导出接口文档
注意:
1.箭头1,此url为访问http://localhost:8080/swagger-ui.html得到的api,如下图所示
swagger导出接口文档
2.箭头2,此目录必须存在,如果目录不存在会导致生成文档失败

Test运行成功如下图所示:

swagger导出接口文档
此时项目已经生成了文档:
swagger导出接口文档
也可以选择将生成的文档合并显示,然后把生成的文档转陈html格式或者world格式
Maven插件完成:

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>./docs/asciidoc/html</outputDirectory>
                    <headerFooter>true</headerFooter>
                    <doctype>book</doctype>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--菜单栏在左边-->
                        <toc>left</toc>
                        <!--多标题排列-->
                        <toclevels>3</toclevels>
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

执行该插件的asciidoctor:process-asciidoc命令之后,就能在docs/asciidoc/html目录下生成最终可用的静态部署HTML了。

相关标签: java