Swagger使用
Swagger学习及生成HTML文档
Swagger
1、集成springboot
第一步：pom
<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.9.2</version>
</dependency>
第二步：swagger在springboot中配置
属性类(省略get/set方法)
/**
* swagger配置,生成api
*
* @author lirui
* @date 2018-07-26
*/
@ConfigurationProperties(prefix = "hyboot.api")
public class HySwaggerProperties {
/**
* 是否开启swagger
*/
private boolean enabled = false;
/**
* API服务标题
*/
private String title;
/**
* API服务描述
*/
private String description;
/**
* API服务版本
*/
private String version;
/**
* Api负责人相关信息
*/
private Leader leader = new Leader();
public static class Leader{
/**
* 负责人姓名
*/
private String name;
/**
* 负责人邮箱
*/
private String email;
}
/**
* 用于生成api的html静态文档,需要配置
*/
private Swagger swagger = new Swagger();
public static class Swagger{
/**
* api 接口获取数据地址
*/
private String apiUrl;
/**
* 生成文件的位置
*/
private String filePath;
}
}
配置application.yml
enabled: false
title: 测试服务api
description: 用于测试
leader:
name: 汤姆
email: tom@163.com
version: 1.0.0
配置类
/**
* swagger配置,生成api
*
* @author lirui
* @date 2018-07-26
*/
@Configuration
@EnableConfigurationProperties({HySwaggerProperties.class})
@EnableSwagger2
public class HySwaggerAutoConfiguration {
private Logger logger = LoggerFactory.getLogger(HySwaggerAutoConfiguration.class);
@Autowired
private ApplicationContext applicationContext;
@Autowired
private HySwaggerProperties hySwaggerProperties;
@Autowired
private ServerProperties serverProperties;
/**
* 定义api生成规则
*
* @return
*/
@Bean
public Docket hyApi() {
return new Docket(DocumentationType.SWAGGER_2)
//group为系统编号（我们spring的id设置为了系统编号）
.groupName(applicationContext.getId())
.apiInfo(apiInfo())
//支持协议
.protocols(Set.of("http", "https"))
.select()
//限制只有在类上加@Api才添加到swagger，默认是都添加的
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//限制只有在方法上加@Api才添加到swagger，默认是都添加的
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
/**
* api相关信息
*
* @return
*/
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
//服务标题
.title(hySwaggerProperties.getTitle() == null ?
applicationContext.getId() + "系统服务API" : hySwaggerProperties.getTitle())
//api服务描述
.description(hySwaggerProperties.getDescription())
//api版本
.version(hySwaggerProperties.getVersion())
//联系人
.contact(
new Contact(hySwaggerProperties.getLeader().getName(), "",
hySwaggerProperties.getLeader().getEmail()))
.build();
}
}
第三步：访问
http://host:port/contentPath/swagger-ui.html
2、生成adoc文件，便于生成HTML/PDF
主要想法是：Swagger2MarkupConverter（可以根据指定url生成adoc文件，用于生成html），如果想调用当前系统生成adoc文件，就必须保证系统启动完成，这样才能根据url访问
第一步：定义生成adoc文件的类
springboot中提供了ApplicationRunner，这个保证了系统启动完执行其中的run方法，所以只要在run方法中调用Swagger2MarkupConverter#from
/**
* 系统运行完执行，用于swagger生成adoc文件，继而产生api接口Html静态文件
* 必须是spring管理的Bean才生效
* @author lirui
* @date 2018-07-26
*/
public class SwaggerCreatAdocRunner implements ApplicationRunner {
/**
* api 接口获取数据地址
*/
private String apiUrl;
/**
* 生成文件的位置
*/
private String filePath;
@Override
public void run(ApplicationArguments args) throws Exception {
try {
//从指定地址获取数据生成接口文档
Swagger2MarkupConverter.from(new URL(apiUrl)).build()
.toFile(Paths.get(filePath));
} catch (MalformedURLException e) {
e.printStackTrace();
}
}
public String getApiUrl() {
return apiUrl;
}
public void setApiUrl(String apiUrl) {
this.apiUrl = apiUrl;
}
public String getFilePath() {
return filePath;
}
public void setFilePath(String filePath) {
this.filePath = filePath;
}
}
第二步：swagger配置初始化SwaggerCreatAdocRunner
就是在上述HySwaggerAutoConfiguration增加了一个SwaggerCreatAdocRunnerspring的bean定义
（添加了默认不开启Swagger的配置）
/**
* swagger配置,生成api
*
* @author lirui
* @date 2018-07-26
*/
@Configuration
@EnableConfigurationProperties({HySwaggerProperties.class, ServerProperties.class})
@EnableSwagger2
@ConditionalOnExpression("${hyboot.api.enabled:false}")
public class HySwaggerAutoConfiguration {
private Logger logger = LoggerFactory.getLogger(HySwaggerAutoConfiguration.class);
public static final String LOCALHOST = "127.0.0.1";
@Autowired
private ApplicationContext applicationContext;
@Autowired
private HySwaggerProperties hySwaggerProperties;
@Autowired
private ServerProperties serverProperties;
/**
* 定义api生成规则
*
* @return
*/
@Bean
public Docket hyApi() {
...
}
/**
* 用于生成swagger API html文档
* http://localhost:8081/demo/v2/api-docs?group=hyboot-demo
*
* @return
*/
@Bean
public SwaggerCreatAdocRunner swaggerRunner() {
//生成api文档的数据来源
String apiUrl = hySwaggerProperties.getSwagger().getApiUrl();
String filePath = ClassLoader.getSystemResource("").getPath()+"api";
//解决window系统路径前带"/"问题
File file = new File(filePath);
filePath = file.getPath();
//设置swagger生成adoc文件启动类
SwaggerCreatAdocRunner swaggerCreatAdocRunner = new SwaggerCreatAdocRunner();
swaggerCreatAdocRunner.setApiUrl(apiUrl);
swaggerCreatAdocRunner.setFilePath(filePath);
if (StringUtils.isBlank(apiUrl)) {
//端口
int port = serverProperties.getPort();
//项目
String contextPath = serverProperties.getServlet().getContextPath();
String group = applicationContext.getId();
apiUrl = "http://" + LOCALHOST + ":" + port + contextPath + "/v2/api-docs?group=" + group;
swaggerCreatAdocRunner.setApiUrl(apiUrl);
}
return swaggerCreatAdocRunner;
}
/**
* api相关信息
*
* @return
*/
public ApiInfo apiInfo() {
...
}
}
第三步：利用上诉生成的adoc文件生成HTML静态文件
这里要用到maven的插件asciidoctor
<!--增加swagger生成html-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>${project.basedir}/target/classes/</sourceDirectory>
<sourceDocumentName>api.adoc</sourceDocumentName>
<outputFile>${project.basedir}/target/classes/api.html</outputFile>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
</attributes>
</configuration>
</plugin>
执行mvn asciidoctor:process-asciidoc
在IDEA中直接点击如图即可：
生成的HTML静态文件
