Swagger接口文档一键生成部署静态文档实现方案

2020-11-17 本文已影响0人 Liucq637

前言

此方案引用了Swagger2Markup实现将Swagger文档离线化。其中采用Java程序调用Maven命令将Swagger2Markup生成的AsciiDoc代码转化成HTML文档，采用Nginx部署静态HTML文档实现在线访问，从而达到文档与源服务隔离部署的目的。

Swagger2Markup 是 Github 上的开源项目。Swagger2Markup 可以将 Swagger 生成的文档转化成流行的格式以便于独立部署和使用，如：Markdown、Confluence、AsciiDoc。
GitHub：https://github.com/Swagger2Markup/swagger2markup

1.环境准备

Linux，本文使用CentOS 7

Nginx，安装过程参考：CentOS 7安装Nginx

JDK 1.8，安装过程参考：CentOS 7安装JDK 1.8

Maven，安装过程参考：CentOS 7安装Maven

2.Nginx配置

2.1 创建静态资源存储路径(需普通账号可访问)，如：/opt/staticfile/swagger
2.2 配置Nginx，使用户能正常访问3.1创建路径下的资源。

    server {
        listen       8081 ;
        server_name  _;
        root         /opt/staticfile/swagger;

        # Load configuration files for the default server block.
        include /etc/nginx/default.d/*.conf;

        location / {
        }

        error_page 404 /404.html;
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
    }

3.部署maven代码

3.1 在普通用户可访问的路径下创建脚本文件，如：api-doc-pom.xml，添加如下代码

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.doc.util</groupId>
    <artifactId>api-doc</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <asciidoc.source>./docs</asciidoc.source>
        <asciidoc.output>./html</asciidoc.output>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <!-- asciidoc文件目录 -->
                    <sourceDirectory>${asciidoc.source}</sourceDirectory>
                    <!-- 生成HTML的路径 -->
                    <outputDirectory>${asciidoc.output}</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!-- 导航栏在左侧 -->
                        <toc>left</toc>
                        <!-- 显示菜单层级数 -->
                        <toclevels>3</toclevels>
                        <!-- 自动打数字序号 -->
                        <sectnums>ture</sectnums>
                    </attributes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

4.编写接口文档管理服务

4.1 本文以Swagger接口形式实现，大家可以自行补充可视化界面。

pom.xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.0.RELEASE</version>
</parent>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>
    <!-- swagger2markup -->
    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>
    <!-- 引用以下两个包是防止生成过程中出现找不到类的异常 -->
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-core</artifactId>
        <version>1.5.16</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.16</version>
    </dependency>
</dependencies>
<repositories>
    <repository>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

Application.java

@Log4j2
@SpringBootApplication
public class Application {

    public static void main(String[] args) throws Exception {
        log.info("=====开始启动=====");
        SpringApplication.run(Application.class, args);
        log.info("=====启动完成=====");
    }
}

DocControlV1.java

@Log4j2
@Api(tags = "静态接口文档生成器")
@RestController
@RequestMapping(value = "/doc", produces = "application/json;charset=UTF-8")
public class DocControlV1 {

    @Autowired
    private Config config;

    /**
     * 生成接口文档
     * 
     * @param param
     * @return
     */
    @ApiOperation(value = "生成接口文档", notes = "生成接口文档")
    @ApiImplicitParam(name = "param", value = "生成接口文档参数", required = true, dataType = "GeneratorParam", paramType = "body")
    @ApiResponses({ @ApiResponse(code = 10000, message = "操作成功", response = String.class),
            @ApiResponse(code = -10001, message = "操作失败") })
    @PostMapping("/generator")
    public RespBody<String> generator(@RequestBody GeneratorParam param) {
        RespBody<String> responseBody = new RespBody<>();
        try {
            // 项目名称
            String project = param.getProject();
            log.info("project : {}", project);

            // 服务地址
            String apiDocsUrl = param.getSwaggerUrl().replace("/swagger-ui.html", "/v2/api-docs");
            log.info("apiDocsUrl : {}", apiDocsUrl);

            // 生成html文档的代码存储路径
            String docsPath = config.getDocPath() + project + "/docs/asciidoc/generated/all";
            log.info("docsPath : {}", docsPath);

            // 输出Ascii到单文件
            Swagger2MarkupConfig asciiConfig = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.ASCIIDOC).withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples().withoutInlineSchema().build();
            Swagger2MarkupConverter.from(new URL(apiDocsUrl)).withConfig(asciiConfig).build()
                    .toFile(Paths.get(docsPath));

            // 数据源存储地址
            String source = config.getDocPath() + project + "/docs";
            log.info("source : {}", source);

            // 输出文档存储地址
            String output = config.getDocPath() + project + "/html";
            log.info("output : {}", output);

            // 组装命令
            String command = "";
            if (config.getOsType().equals("linux")) {
                command = "mvn asciidoctor:process-asciidoc -f={0} -Dasciidoc.source={1} -Dasciidoc.output={2}";
            } else {
                command = "cmd /c mvn asciidoctor:process-asciidoc -f={0} -Dasciidoc.source={1} -Dasciidoc.output={2}";
            }
            command = command.replace("{0}", config.getPomPath());
            command = command.replace("{1}", source);
            command = command.replace("{2}", output);
            log.info("command : {}", command);

            // 执行命令
            Runtime runtime = Runtime.getRuntime();
            Process pro;
            pro = runtime.exec(command);
            int status = pro.waitFor();
            if (status == 0) {
                log.info("The command was executed success");
                String docUrl = config.getDocUrl() + project + "/html/all.html";
                log.info("docUrl : {}", docUrl);
                responseBody.setCode(10000);
                responseBody.setMsg("操作成功");
                responseBody.setValue(docUrl);
            } else {
                log.info("The command was executed fail");
                responseBody.setCode(-10001);
                responseBody.setMsg("操作失败");
            }
            pro.destroy();
        } catch (IOException e) {
            e.printStackTrace();
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        return responseBody;
    }
}

RespBody.java

@Data
public class RespBody<T> {

    @ApiModelProperty(value = "响应码", position = 1)
    private Integer code;
    @ApiModelProperty(value = "响应信息", position = 2)
    private String msg;
    @ApiModelProperty(value = "响应内容", position = 3)
    private T value;
}

GeneratorParam.java

@Data
public class GeneratorParam implements Serializable {

    private static final long serialVersionUID = 5949232055776328416L;

    @ApiModelProperty(value = "项目名称：xxx-app-api，必填", required = true, position = 1)
    private String project;
    @ApiModelProperty(value = "Swagger接口文档地址：http://localhost:8002/swagger-ui.html，必填", required = true, position = 2)
    private String swaggerUrl;
}

Config.java

@Data
@Component
public class Config {

    // 静态接口文档存储路径
    @Value("${doc-path:/opt/}")
    private String docPath;
    // maven代码存储路径
    @Value("${pom-path:/opt/pom.xml}")
    private String pomPath;
    // 系统类型
    @Value("${os-type:linux}")
    private String osType;
    // 接口文档访问地址
    @Value("${doc-url:http://127.0.0.1:8080/}")
    private String docUrl;
}

Swagger2.java

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.doc.control")).paths(PathSelectors.any()).build()
                .useDefaultResponseMessages(false); // 关掉默认的http响应码;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("静态接口文档生成器API文档").description("静态接口文档生成器API文档").version("1.0.0").build();
    }
}

application.yml

# 服务端口
server.port: 5000
# 静态接口文档存储路径，注意最后要带 "/"
doc-path: /opt/staticfile/swagger/
# maven代码存储路径
pom-path: /opt/staticfile/swagger/api-doc-pom.xml
# 接口文档访问地址（Nginx），注意最后要带 "/"
doc-url: http://127.0.0.1:8080/
# 操作系统：linux、windows
os-type: linux

4.2 服务自行编译部署到Linux环境
4.3 服务启动后，访问服务swagger文档，如：http://localhost:5000/swagger-ui.html

4.4 调用接口自动生成并部署静态接口文档，获得接口文档访问地址，文档结构如下

Swagger接口文档一键生成部署静态文档实现方案

前言

1.环境准备

2.Nginx配置

3.部署maven代码

4.编写接口文档管理服务

猜你喜欢

热点阅读