springboot swagger2 构建api文档
简介：
Swagger的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。
我觉得把Swagger当成一种开发工具就好，省去了手写文档的步骤，生成文档并能测试，注解的方式让其他人看代码也更加清楚方便。想了解更多请自己查看官方文档！
1. 添加pom 依赖
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
<swagger-ui-layer.version>0.0.4</swagger-ui-layer.version>
<swagger.version>2.8.0</swagger.version>
</properties>
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
<!-- swagger2 -->
2.Swagge2Config 配置
@Configuration
public class Swagge2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.globalOperationParameters(setHeaderToken())
// 这里swagger请求会变成http://http/***/records/export
// .host("localhost:10340/")
.select()
.apis(RequestHandlerSelectors.basePackage("com.test.controller"))
.paths(PathSelectors.any()).build();
}private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("senseguard-map-management api").description("地图管理").version("1.0")
.termsOfServiceUrl("http://www.github.com/kongchen/swagger-maven-plugin")
.build();
}private List<Parameter> setHeaderToken() {
ParameterBuilder builder = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
builder.name("accessToken").description("token").modelRef(new ModelRef("string")).parameterType("header")
.required(false);
pars.add(builder.build());
return pars;
}
3.pom配置插件
<build>
<finalName>senseguard-map-management</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.3.2</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<encoding>UTF-8</encoding>
<optimize>true</optimize>
<debug>true</debug>
<showDeprecation>true</showDeprecation>
<showWarnings>false</showWarnings>
<compilerArguments>
<verbose />
<bootclasspath>${java.home}/lib/rt.jar${path.separator}${java.home}/lib/jce.jar</bootclasspath>
</compilerArguments>
</configuration>
</plugin><plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.5</version>
<configuration>
<apiSources>
<apiSource>
<springmvc>true</springmvc>
<locations>com.test.controller</locations><!--
Controller所在的位置 -->
<host>localhost:8088</host>
<basePath>/swagger</basePath><!--生成的json 文件路径-->
<schemes>http,https</schemes>
<info>
<title>${artifactId}</title>
<version>v1</version>
<description>**科技有限公司开发API集</description>
<termsOfService>http://www.baidu.com</termsOfService>
</info>
<!--html文档输出功能的模板文件 -->
<!--<templatePath>${basedir}/src/test/resources/swagger_template/strapdown.html.hbs</templatePath> -->
<!--html文档输出的位置 -->
<!--<outputPath>${project.build.directory}/swagger-ui/swagger_document.html</outputPath> -->
<swaggerDirectory>${project.build.directory}/swagger-ui</swaggerDirectory><!--定义API描述文档的输出目录 -->
<outputFormats>yaml,json</outputFormats><!--支持yaml和json格式 -->
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
<pluginManagement>
<plugins>
<!--This plugin's configuration is used to store Eclipse m2e settings
only. It has no influence on the Maven build itself. -->
<plugin>
<groupId>org.eclipse.m2e</groupId>
<artifactId>lifecycle-mapping</artifactId>
<version>1.0.0</version>
<configuration>
<lifecycleMappingMetadata>
<pluginExecutions>
<pluginExecution>
<pluginExecutionFilter>
<groupId>
com.github.kongchen
</groupId>
<artifactId>
swagger-maven-plugin
</artifactId>
<versionRange>
[3.1.5,)
</versionRange>
<goals>
<goal>generate</goal>
</goals>
</pluginExecutionFilter>
<action>
<ignore></ignore>
</action>
</pluginExecution>
</pluginExecutions>
</lifecycleMappingMetadata>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
4. 命令
5.执行
此时json 文件已经生成