将Swagger导出HTML、PDF和MARKDOWN
在网上突然看到了有别的方式，在这里记录一下，比这个简单很多，容易理解的
1.在依赖中还是有swagger2Markup
io.github.swagger2markup
swagger2markup
1.3.1
2.在pom.xml的build中增加插件，这个插件是用于生成adoc文件的，一共四个
1.definitions.adoc 保存request的对象体信息
2.overview.adoc 整体的描述
3.paths.adoc 所有接口的具体信息
4.security.adoc 几乎无用
里面的swaggerInput配置，配置获取swagger.json的url，ip和port需要修改为对应的，对swagger了解比较多的，swagger会有分组的配置，如果配置了分组，需要将url带上分组信息，如http://localhost:8082/v2/api-docs?group=xxxx，如果配置了分组，而没有group参数，在执行命令时会不成功
outputDir配置了生成出来的文件的路径，试过了一下，建议不要配置在src下面，在删除内容的时候，容易将src都删除了，很坑
io.github.swagger2markup
swagger2markup-maven-plugin
1.2.0
http://localhost:8082/v2/api-docs
src/docs/asciidoc/generated
ASCIIDOC
3.也是在build中增加插件，配置了生成html和pdf的相关配置
org.asciidoctor
asciidoctor-maven-plugin
1.5.3
org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.10.1
org.jruby
jruby-complete
1.7.21
src/docs/asciidoc/generated
coderay
left
output-html
generate-resources
process-asciidoc
html5
src/docs/asciidoc/html
output-pdf
generate-resources
process-asciidoc
pdf
src/docs/asciidoc/pdf
4.上面的配置完成后，执行命令
1.mvn swagger2markup:convertSwagger2markup
2.mvn generate-resources
目前来说，上面的方法都是可以执行成功，将html和pdf生成出来的，不建议在向下看，比较老的方式，很繁琐
----------------------------------------------------------------------------------------------------------------------------------------------------------------------
首先，我的项目是SpringBoot1.3.2+Spring4.2.3+JaveSE1.7+JUNIT4
之前也不会，就在网上找了一些教程，但是到我的实际项目中，都会有问题，今天只是记录下都需要怎么样去实现与出现的一些问题
Swagger的配置
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.StopWatch;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
private final Logger log = LoggerFactory.getLogger(SwaggerConfiguration.class);
@Bean
public Docket engineDocket() {
Docket swaggerSpringMvcPlugin = new Docket(DocumentationType.SWAGGER_2)
.groupName("ENGINE_API").apiInfo(cmApiInfo()).select()
.paths(or(regex("/ops/v1/execEngine.*"), regex("/ops/v1/exec/executor.*"))) // and by paths
.build();
return swaggerSpringMvcPlugin;
}
@Bean
public Docket cmDocket() {
Docket swaggerSpringMvcPlugin = new Docket(DocumentationType.SWAGGER_2).groupName("CM_API")
.apiInfo(cmApiInfo()).select().paths(or(regex("/conf/v1/.*"))) // and by paths
.build();
return swaggerSpringMvcPlugin;
}
@Bean
public Docket opDefinitionkDocket() {
Docket swaggerSpringMvcPlugin = new Docket(DocumentationType.SWAGGER_2)
.groupName("OpDefinition_API").apiInfo(opDefApiInfo()).select()
.paths(or(regex("/ops/v1/opdefinition.*"))) // and by paths
.build();
return swaggerSpringMvcPlugin;
}
@Bean
public Docket opJobDocket() {
Docket swaggerSpringMvcPlugin = new Docket(DocumentationType.SWAGGER_2)
.groupName("OpJob_API").apiInfo(opJobApiInfo()).select()
.paths(or(regex("/ops/v1/opjob.*"), regex("/ops/v1/plan.*"))) // and by paths
.build();
return swaggerSpringMvcPlugin;
}
@SuppressWarnings("unchecked")
@Bean
public Docket dashboardDocket() {
Docket swaggerSpringMvcPlugin = new Docket(DocumentationType.SWAGGER_2)
.groupName("Dashboard_API").apiInfo(dashboradApiInfo()).select()
.paths(or(regex("/cm/v1/dashboard.*"))) // and by paths
.build();
return swaggerSpringMvcPlugin;
}
@SuppressWarnings("unchecked")
@Bean
public Docket inspectDocket() {
Docket swaggerSpringMvcPlugin = new Docket(DocumentationType.SWAGGER_2)
.groupName("Inspect_API").apiInfo(inspectApiInfo()).select()
.paths(or(regex("/inspect/v1/.*"))) // and by paths
.build();
return swaggerSpringMvcPlugin;
}
@SuppressWarnings("unchecked")
@Bean
public Docket sysMgtDocket() {
Docket swaggerSpringMvcPlugin = new Docket(DocumentationType.SWAGGER_2)
.groupName("SysMgt_API").apiInfo(opLogApiInfo()).select()
.paths(or(regex("/ops/v1/oplog.*"), regex("/cms/v1/sys/dept.*"),
regex("/cms/v1/sys/account.*"), regex("/cms/v1/sys/role.*"), regex("/cms/v1/login"),
regex("/cms/v1/logout"), regex("/cms/v1/sys/permission.*"))) // and by paths
.build();
return swaggerSpringMvcPlugin;
}
private ApiInfo cmApiInfo() {
return new ApiInfoBuilder()
.title("此分组的具体信息")
.description("描述信息")
.version("1.0")
.contact(new Contact("公司名称", "公司主页地址", "联系人邮件"))
.build();
}
private ApiInfo opDefApiInfo() {
return new ApiInfoBuilder()
.title("此分组的具体信息")
.description("描述信息")
.version("1.0")
.contact(new Contact("公司名称", "公司主页地址", "联系人邮件"))
.build();
}
private ApiInfo opJobApiInfo() {
return new ApiInfoBuilder()
.title("此分组的具体信息")
.description("描述信息")
.version("1.0")
.contact(new Contact("公司名称", "公司主页地址", "联系人邮件"))
.build();
}
private ApiInfo dashboradApiInfo() {
return new ApiInfoBuilder()
.title("此分组的具体信息")
.description("描述信息")
.version("1.0")
.contact(new Contact("公司名称", "公司主页地址", "联系人邮件"))
.build();
}
private ApiInfo opLogApiInfo() {
return new ApiInfoBuilder()
.title("此分组的具体信息")
.description("描述信息")
.version("1.0")
.contact(new Contact("公司名称", "公司主页地址", "联系人邮件"))
.build();
}
private ApiInfo inspectApiInfo() {
return new ApiInfoBuilder()
.title("此分组的具体信息")
.description("描述信息")
.version("1.0")
.contact(new Contact("公司名称", "公司主页地址", "联系人邮件"))
.build();
}
}
注意：强调一下，这里面我们用了Swagger分组的方式，也就是上面的groupName内容，这个
pom.xml配置
4.0.0
com.chinamobile.iot
restdocs
1.0-SNAPSHOT
org.springframework.boot
spring-boot-starter-parent
1.5.2.RELEASE
${project.build.directory}/generated-snippets
${project.basedir}/docs/asciidoc
src/asciidoc
${project.build.directory}/asciidoc/html
${project.build.directory}/asciidoc/pdf
com.alibaba
fastjson
1.2.8
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-starter-test
io.springfox
springfox-swagger2
2.6.1
io.springfox
springfox-swagger-ui
2.6.1
org.springframework.restdocs
spring-restdocs-mockmvc
1.1.2.RELEASE
test
io.springfox
springfox-staticdocs
2.6.1
io.github.swagger2markup
swagger2markup
1.3.2
org.apache.maven.plugins
maven-surefire-plugin
org.asciidoctor
asciidoctor-maven-plugin
1.5.3
org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.14
org.jruby
jruby-complete
1.7.21
${asciidoctor.input.directory}
index.adoc
book
left
3
${generated.asciidoc.directory}
output-html
test
process-asciidoc
html5
${asciidoctor.html.output.directory}
output-pdf
test
process-asciidoc
pdf
${asciidoctor.pdf.output.directory}
生成HTML和PDF的测试类
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import com.idcos.cms.server.CloudConfServer;
import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.Swagger2MarkupConverter;
import springfox.documentation.staticdocs.SwaggerResultHandler;
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest(classes = Application.class)//工程的启动类
public class SwaggerToHTMLandPDFTest {
private String snippetDir = "target/generated-snippets";
private String swaggerOutput = "src/asciidoc";
private String adocDir = "docs/asciidoc/src/asciidoc";
@Autowired
private MockMvc mockMvc;
@Test
public void Test() throws Exception {
// 得到swagger.json,写入outputDir目录中
mockMvc.perform(get("/v2/api-docs?group=SysMgt_API").accept(MediaType.APPLICATION_JSON))
.andDo(SwaggerResultHandler.outputDirectory(swaggerOutput).build())
.andExpect(status().isOk())
.andReturn();
// 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir
Swagger2MarkupConverter.from(swaggerOutput + "/swagger.json")
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
.withExamples(snippetDir)
.build()
.intoFolder(adocDir);// 输出
}
}生成MARKDOWN的测试类
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.nio.file.Paths;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import com.idcos.cms.server.CloudConfServer;
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 springfox.documentation.staticdocs.SwaggerResultHandler;
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "src/asciidoc")
@RunWith(SpringRunner.class)
@SpringBootTest(classes = CloudConfServer.class)
public class SwaggerToMarkdownTest {
private String outputDir = "src/asciidoc";
@Autowired
private MockMvc mockMvc;
//生成markdowd文档
@Test
public void Test1() throws Exception{
// 得到swagger.json,写入outputDir目录中
mockMvc.perform(get("/v2/api-docs?group=SysMgt_API").accept(MediaType.APPLICATION_JSON))
.andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
.andExpect(status().isOk())
.andReturn();
//生成markdown的配置
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.build();
//获取swagger.json文件，输出到outputDir中
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(Paths.get("src/asciidoc/swagger.json")).withConfig(config).build();
converter.toFile(Paths.get(outputDir));
}
}
注意：在上面的mockMvc获取swagger.json文件的地址中，加入了group的查询参数，我之前在网上搜索的教程中，只有一个说了这个问题，但是也不是很清楚，导致我获取json文件很长时间。如果在swagger的配置中（看上面的SwaggerConfigration），进行了分组，在获取swagger.json的时候，就需要加上group这个参数，如果没有分组，就不用加
顺便提一下，如果你学过swagger，swagger的访问地址http://localhost:8080/swagger-ui.html，就可以看到接口的所有信息，并且进行测试，还有一个地址http://localhost:8080/v2/api-docs，打开这个地址，页面就显示一堆数据，就是swagger.json文件的具体信息，如果分组，还是需要加上group这个参数。
还需要有一个文件index.adoc
include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]当在运行一个测试类之后，会生成swagger.json，测试类的第二个方法，会生成三个文件
这三个文件就是把swagger.json文件进行了处理，为构建html和pdf生成adoc文件
步骤（生成html和pdf）：
1.运行第一个测试类，生成swagger.json和三个adoc文件
2.命令行，运行mvn clean test
3.在target/asciidoc下面就会生成html和pdf
生成markdown文件，直接运行第二个测试类
注意：生成pdf的时候，对中文的支持很不好，会缺少文字，由于使用的分组，只能一个个的文档生成
我在构建文档过程中出现的问题
1.升级Springboot（1.3.2升级到1.5.2）
由于我的项目是使用mongo数据库的，配置文件
升级了之后，
其他的不用动
2.swagger-models的jar包出问题
之前这个jar包是不需要在pom.xml文件中引用的，是springfox.swagger2的包引用的，但是在运行第二个测试类的时候，有一个枚举类总是缺少元素，只能把这个包升级，在pom.xml中添加
解决此问题
最后在强调一下，在测试的过程中，会有一些文件路径的问题，这个只能具体测试的时候，去解决了
特此感谢
http://blog.csdn.net/fly910905/article/details/79131755#comments