SpringBoot整合Swagger2的完整过程记录

SpringBoot整合Swagger2的完整过程记录

目录前言一、Spring Boot Web 整合 Swagger2 过程1.1、添加 Swagger2 相关依赖1.2、配置 Swagger2 配置类二、配置 Swagger2 接口常用注解2.1、@Api 请求类说明2.2、@ApiOperation 方法的说明2.3、@ApiImplicitParams 和 @ApiImplicitParam 方法参数说明2.4、http://@ApiResponses 和 @ApiRehttp://sponse 方法返回值的说明2.5、@ApiModel 和 @ApiModelProperty2.6、其他注解总结

前言

springBoot作为微服务首选框架，为其他服务提供大量的接口服务。接口对接方需要实时最近的接口文档。

swagger可以通过代码和注释自动为web项目生成在线文档，这里使用swagger。

当 SpringBoot 代码中 SpringMVC 使用自动化配置类 WebMvcAutoConfiguration 时，其整合 Swagger2 的方法如下。

如果 SpringMVC 的配置过程使用了 WebMvcConfigurationSupport；则如下的整合方法不适合。

一、Spring Boot Web 整合 Swagger2 过程

Spring Boot Web 项目整合 Swagger2 主要有两个过程：

添加 Swagger2 相关依赖。

配置 Swagger2 配置类。

1.1、添加 Swagger2 相关依赖

首先要对 Spring Boot Web 的项目，添加 Swagger2 相关的依赖：

org.springframework.boot

spring-boot-starter-web

io.springfox

springfox-swagger2

2.9.2

io.springfox

springfox-swagger-ui

2.9.2

1.2、配置 Swagger2 配置类

@Configuration

@EnableSwagger2

public class Swagger {

//创建 Docket 的Bean

@Bean

public Docket docket(){

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

http:// //select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现

.select()

//要扫描的包

.apis(RequestHandlerSelectors.basePackage("com.example.controller"))

//选择API路径

.paths(PathSelectors.any())

.build();

}

​ //创建文档的基本信息

public ApiInfo apiInfo(){

return new ApiInfoBuilder()

.title("Swagger UI 的标题")

.description("用restful风格写接口")

.termsOfServiceUrl("")

.version("1.0")

.build();

}

}

二、配置 Swagger2 接口常用注解

2.1、@Api 请求类说明

写在controller类定义上方,用于说明类的作用。

@Api(value = "Swagger Test Control",

description = "演示Swagger用法的Control类",

tags = "Swagger Test Control Tag")

2.2、@ApiOperation 方法的说明

写在REST接口上方，用于说明方法的作用。

@ApiOperation(

value="创建用户",

notes="根据User对象创建用户")

2.3、@ApiImplicitParams 和 @ApiImplicitParam 方法参数说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

@ApiImplicitParam：对单个参数的说明

name：参数名

value：参数的汉字说明、解释

required：参数是否必须传

paramType：参数放在哪个地方

header --> 请求参数的获取：@RequestHeader

query --> 请求参数的获取：@RequestParam

path（用于restful接口）--> 请求参数的获取：@PathVariable

body（请求体）--> @RequestBody User user

form（普通表单提交）

dataType：参数类型，默认String，其它值dataType="int"

defaultValue：参数的默认值

--------------------------------------------------------------------

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "ID", dataType = "Long"),

@ApiImplicitParam(name = "user", value = "用户", dataType = "User")

})

2.4、@ApiResponses 和 @ApiResponse 方法返回值的说明

@ApiResponses：方法返回对象的说明

@ApiResponse：每个参数的说明

code：数字，例如400

message：信息，例如"请求参数没填好"

response：抛出异常的类

-------------------------------------------------------------------

@ApiResponses({

@ApiResponse(code = 400, message = "权限不足"),

@ApiResponse(code = 500, message = "服务器内部异常") }

)

2.5、@ApiModel 和 @ApiModelProperty

@ApiModel 用于javaBean 上面，表示一个JavaBean。这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候。

@ApiModelProperty 用对象接收参数时，描述对象的一个字段。

@ApiModel( description = "学生")

public class Student {

@ApiModelProperty(value = "主键id")

private String id;

@ApiModelProperty(value = "名称", required = true)

private String name;

@ApiModelProperty(value = "年龄", required = true)

private int age;

}

2.6、其他注解UiTVWTCEPm

@ApiIgnore ：使用该注解忽略这个API，不对这个接口生成文档。

@ApiError：发生错误返回的信息

总结

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。