SpringBoot 简单集成 Swagger 方法
原创
Swagger 用于生成、描述、调用和可视化RESTful风格的Web服务。
优点
1：提高工作效率，提升项目API文档品质，因为日常项目研发的过程中产出高质量的文档是非常繁琐且费时的工作。
2：避免因需求的变化，导致文档与业务不一致的情况发生。
使用版本 Swagger 2.9.2
第一步：
POM文件引入的jar
<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 配置类
@Configuration
@EnableSwagger2
public class Swagger2Conf implements WebMvcConfigurer {
@Bean
public Docket createRestApi(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("系统接口")
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
//加了ApiOperation注解的类，才生成接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
/**
*
* @return
*/
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Spring Boot 中使用Swagger2 构建RestFul Api")
.description("这是 descrption 描述")
.termsOfServiceUrl("http://www.baidu.com")
.contact(new Contact("张三","localhost:8088/swagger-ui.html","111111@qq.com"))
.version("1.0")
.build();
}
}说明：(引用《Spring Boot 从入门到实战》)
@Configuration注解让Spring Boot来加载该类配置。
@EnableSwagger2注解启用Swagger2，通过配置一个Docket Bean，来配置映射路径和要扫描的接口所在的位置。
apiInfo主要配置Swagger2文档网站的信息，比如网站的标题、网站的描述、使用的协议等。
需要注意的是：
1）basePackage可以在SwaggerConfig中配置com.example.demo.controller，也可以在启动器ComponentScan中配置。
2）需要在SwaggerConfig中配置Swagger的URL映射地址：/swagger-ui.html。
第四步：
配置Controller类
@Api(tags = {"用户接口"})
@RestController
public class HelloController {
@ApiImplicitParam(name="userId",value = "用户ID",dataType = "int")
@ApiOperation(value = "用户ID",notes = "用户的ID")
@RequestMapping("/helloword")
public String testHello(int userId){
return userId+"";
}
}属性说明：
1）@Api注解：使用在类上，表明是swagger资源，用来给整个控制器（Controller）增加说明。
属性说明：
tags：说明该类的作用，可以在UI界面上看到的注解
value：无太大意义，可写接口地址
2）@ApiOperation注解：用来给各个API方法增加说明。
属性说明：
values = “说明方法的作用”
notes=”方法的备注说明”
3）@ApiImplicitParam 注解：用来给参数增加说明。
属性说明：
1.name：参数名
2. value：参数的具体意义、作用
3.required：参数是否必填
4.dataType：参数的数据类型
5.paramType：
查询参数类型，有几种形式：
path（以地址类型提交数据）
query（直接跟参数完成自动映射赋值）
body（以流的形式提交，仅支持post）
header（参数在request headers里边提交）
form（以form表单的形式提交，仅支持post）
4）@ApiImplicitParams注解：用来给参数增加说明。用于方法，包含多个@ApiImplicitParam,形式如下.
@ApiImplicatParams（{
@ApiImplicitParam（）,
@ApiImplicitParam（）
}）
第五步：
启动项目 启动成功后 通过 http://localhost:{项目端口号}/swagger-ui.html 进行 访问
第六步：
如果启动后无法访问链接且报404错误，可在SpringBoot 配置文件中配置如下内容
spring.mvc.pathmatch.matching-strategy=ant_path_matcher效果
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
腾讯云开发者
