什么是swagger2?
接口文档生成工具,解决前后端分离开发,文档对接的痛点!
主要使用:swagger editor,swagger ui
踩坑:从Spring-boot2.0以上在集成swagger后,配置WebConfig时不要extends WebMvcConfigurationSupport,需要修改为最新的implements WebMvcConfigurer,不然访问swagger-ui.html时读取不到swagger-ui的静态资源文件。
1、 添加依赖
注意:springboot2.0x,这里我使用的是swagger2的2.8.0版本。
<!--swagger2 依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
2、 启动类加入注解
@EnableSwagger2
3、设置初始化配置类
package com.xxx.xx.data.center.config;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
/**
* 指定文档扫描路径
* @return
*/
@Bean
public Docket createRestApi() {
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("access_token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2)
.enable(true)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.bosssoft.gp.data.center.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars);
}
/**
* 文档基本信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXXXXXX数据交换中心")
.description("数据交换中心")
.version("1.0")
.build();
}
}
4、映射配置类,注意要实现 WebMvcConfigurer
package com.xxx.xx.data.center.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* swagger2
* 将jar包中的静态资源映射
*/
@Configuration
public class WebMvcConfiguration implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
5、配置文件设置Swagger2页面地址:
注意:swagger2不需要加入项目路径:
###swagger2页面
eureka.instance.status-page-url=http://127.0.0.1:7007/swagger-ui.html
6、页面展示
6.1 查看注册中心注册的实例
6.2 查看文档
额外说明
前面提到配置项:
1)WebMvcConfiguration
说白了,就是将引入的jar包的相关静态资源映射到项目下
2) SwaggerConfiguration
swagger的方便之处就是,通过页面可以获取接口参数,调用接口,响应数据,很类似于postman!
这里设置了一个token参数,表示调用接口需要在header上传入,而不是通过在controller使用@Api引入。
效果如图:
3)其他声明:
关于在配置项我们设置的扫描包问题
一般情况下,都是切入到controller,
对于不需要加入在页面上展示的接口,使用@ApiIgnore
效果如图:
对于需要引入文档的
当然。这个@ApiOperation有很多个参数,这里给出
主要属性有access、accessMode、allowableValues、allowEmptyValue(是否允许为空)、dataType(数据类型)、example(示例)、hidden(是否隐藏)、name(名称)、notes、required(是否必需)、value(说明)等。