Springboot Swagger 在线接口文档
1、Swagger配置
(1)引入依赖
<properties>
<swagger.version>2.7.0</swagger.version>
</properties>
<!-- Swagger -->
<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> -->
<!-- 替换swagger ui -->
<dependency>
<groupId>com.drore.cloud</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.4</version>
</dependency>
(2)Swagger配置类
package com.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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 Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// .apis(RequestHandlerSelectors.basePackage("com.demo.controller")) //把controller包下的所有方法都转为restful api
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //只把有@ApiOperation注解的方法转为restful api
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Swagger2说明 https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel")
.termsOfServiceUrl("http://localhost:8080/")
.contact(new Contact("wzf", "https://swagger.io/", "wangzengfeng@comba.com.cn"))
.version("1.0")
.build();
}
}
(3)swagger的其他使用方式
参考:https://github.com/SpringForAll/spring-boot-starter-swagger 下载github上面的源码,放到自己工程下面,之后就可以在配置文件里面配置,省去上面的代码配置
swagger:
title: RESTful APIs
description: API接口文档
version: 1.0
globalOperationParameters[0]:
name: access_token
description: token
parameterType: query
modelRef: string
required: true
docket:
env:
base-package: com.demo.web.environment.controller
system:
base-package: com.demo.web.system.controller
2、访问与调试
http://localhost:8080/doc.html
调试:
3、参考
Swagger-Bootstrap-UI是Swagger的前端UI实现,采用jQuery+bootstrap实现,目的是替换Swagger默认的UI实现Swagger-UI,使文档更友好一点:
https://git.oschina.net/xiaoym/swagger-bootstrap-ui
https://oss.sonatype.org/#nexus-search;quick~swagger-bootstrap-ui
4、Api接口添加全局参数
@Configuration
@EnableSwagger2
public class Swagger2 {
private List<Parameter> parameters (){
ParameterBuilder aParameterBuilder = new ParameterBuilder();
aParameterBuilder
//参数类型支持header, cookie, body, query etc
.parameterType("query")
//参数名
.name("access_token")
.description("token")
//指定参数值的类型
.modelRef(new ModelRef("string"))
//非必需false,这里是全局配置,然而在登陆的时候是不用验证的
.required(true).build();
List<Parameter> aParameters = new ArrayList<Parameter>();
aParameters.add(aParameterBuilder.build());
return aParameters;
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("base")
.globalOperationParameters(parameters())
.select()
//只把有@ApiOperation注解的方法转为restful api
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
}
5、问题记录
在通过swagger2在线测试接口时候,如果url中有{id},需要添加paramType=”path”,否则无法从路径中获得id值
@ApiImplicitParams({
@ApiImplicitParam(name =” id”, value = ”用户ID”, required = true, paramType =”path”, dataType =” Long”),
@ApiImplicitParam(name = ”user”, value = ”用户详细实体user”, required = true, paramType =” body”, dataType = ”User”)
})
要定义paramType, paramType 有五个可选值 : path, query, body, header, form
6、生成离线文档
(1)创建文件夹
asciidoctor asciidoctor有maven插件,可以自动把acsiidoc文件转成html和pdf,能自动生成目录,非常方便 先在工程下创建docs/asclidoc这个文件:
文件内容是:
include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]
意思就是引入三个文件
(2)Maven配置
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<configuration>
<sourceDirectory>${project.basedir}/docs/asciidoc</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${project.build.directory}/asciidoc</generated>
</attributes>
</configuration>
<!-- Since each execution can only handle one backend, run separate executions
for each desired output type -->
<executions>
<execution>
<id>output-html</id>
<phase>test</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<doctype>book</doctype>
<!--<outputDirectory>${project.basedir}/docs/asciidoc/html</outputDirectory> -->
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
####(3)运行maven build
运行成功后,在E:\Workspaces\Comba-Api\target\generated-docs文件夹下会生成