swagger是一款优秀的api文档输出工具
基本介绍请移步:swagger官网
- swagger配置:
<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>
package com.ppx.swaggerdoc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@SpringBootApplication
public class SwaggerdocApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerdocApplication.class, args);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("API接口文档")
.description("用户信息管理")
.version("1.0.0")
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.ppx.swaggerdoc")) //这里写的是API接口所在的包位置
.paths(PathSelectors.any())
.build();
}
}
- 输出文档配置:
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
<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>
@RunWith(SpringRunner.class)
public class exportConfig {
@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:8765/v2/api-docs?group=api"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/asciidoc/generated/all"));
}
}
maven命令:mvn asciidoctor:process-asciidoc 和 mvn generate-resources
此工具的方便之处是不需要所有的项目都配置,只要有一个项目配置,其他项目开启后,能读取swagger的json文件,即可输出文档。
但是注意swagger还是要引入,api参数解释也要做,对于老项目通过注释的那种还是写个代码生成器生成一下。
demo:
swaggerdoc module
参考:
https://www.cnblogs.com/wg1234/p/9962237.html