Springboot整合Swagger学习笔记

1：在pom文件中导入下面的依赖

<dependency>    <groupId>com.didispace</groupId>    <artifactId>spring-boot-starter-swagger</artifactId>    <version>1.4.1.RELEASE</version></dependency>

2：需要在springboot的main方法类上面注解上标签@EnableSwagger2Doc

package com.suiyu.swagger;import com.didispace.swagger.EnableSwagger2Doc;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;@EnableSwagger2Doc@SpringBootApplicationpublic class SwaggerApplication {    public static void main(String[] args) {        SpringApplication.run(SwaggerApplication.class, args);    }}

3：在全局的配置yml文件中配置下面的信息

swagger:  enabled: true #开启swagger  title: swagger的标题  description: swagger的描述  version:  swagger的版本  license:  swagger的许可证  license-url: swagger的许可证地址  terms-of-service-url: 服务条款url  contact:    name: 维护人姓名    email: 维护人邮箱    url: 维护人url  base-package: swagger的扫描包  base-path: 需要处理的基础URL规则

4：一些常用的注解

4.1：@Api 这个注解用在controller接口上面的,有下面的这些属性

属性名称 备注 value url的路径值 tags 对当前controller接口的标签,如果设置这个值、value的值会被覆盖 description 对当前controller接口的描述 basePath 基本路径可以不配置 position 如果配置多个Api 想改变显示的顺序位置 produces For example, “application/json, application/xml” consumes For example, “application/json, application/xml” protocols Possible values: http, https, ws, wss. authorizations 高级特性认证时配置 hidden 配置为true 将在文档中隐藏

使用demo(一般只需要写下tags属性,表明当前controller的一些简单信息就好了):

@Api(tags = "图书管理的controller")public class BookController {}

4.2：@ApiOperation 用在方法上,说明方法的作用,每一个url资源的定义

属性名称 备注 value 当前方法的简单描述 tags 方法上面最好不要用这个属性(作用跟controller上面使用一样) notes 实现这个方法需要注意的事项、方法的一些说明 extensions 扩展属性 position 如果配置多个Api 想改变显示的顺序位置 produces For example, “application/json, application/xml” consumes For example, “application/json, application/xml” protocols Possible values: http, https, ws, wss. authorizations 高级特性认证时配置 hidden 配置为true 将在文档中隐藏 response 返回的对象 responseContainer 这些对象是有效的 “List”, “Set” or “Map”.，其他无效 httpMethod “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”,当在RequestMapping上面写上了Method的时候那么就不需要写 code http的状态码 默认 200

使用demo:

@ApiOperation(value = "获图书细信息", notes = "根据url的id来获取详细信息")

4.3：@ApiImplicitParam 用来描述参数的信息

属性 取值 作用 paramType 查询参数类型 path 以地址的形式提交数据 query 直接跟参数完成自动映射赋值 body 以流的形式提交 仅支持POST header 参数在request headers 里边提交 form 以form表单的形式提交 仅支持POST dataType 参数的数据类型 只作为标志说明，并没有实际验证 Long String 其他.. name 接收参数名 value 接收参数的意义描述 required 参数是否必填 true 必填 false 非必填 defaultValue 默认值

使用demo:

@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long", paramType = "path")

4.4：@ApiImplicitParams 如果一个方法有多个的参数,那么可以使用@ApiImplicitParams注解将@ApiImplicitParam注解包起来,表示多个参数

使用demo:

@ApiImplicitParams({        @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long", paramType = "path"),        @ApiImplicitParam(name = "book", value = "图书实体book", required = true, dataType = "Book")})

4.5：@ApiResponse 用在方法上面,自定义返回的状态吗的一些信息

属性名称 备注 code http的状态码 message 造成这个状态吗的原因描述 response 默认响应类 Void reference 参考ApiOperation中配置 responseHeaders 参考 ResponseHeader 属性配置说明 responseContainer 参考ApiOperation中配置

使用demo:

    @ApiResponses({@ApiResponse(code = 400, message = "Invalid Order")})

4.6：@ApiResponses 用于表示一组@ApiResponse

使用demo:

@ApiResponses({@ApiResponse(code = 400, message = "Invalid Order"), @ApiResponse(code = 404, message = "not find")})

4.7：@ResponseHeader 响应头设置

属性名称 备注 name 响应头名称 description 头描述 response 默认响应类 Void responseContainer 参考ApiOperation中配置

使用demo:

@ResponseHeader(name="head1",description="response head conf")

4.8：其他

• @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

• @ApiModelProperty：描述一个model的属性。