Springboot整合Swagger学习笔记

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
@SpringBootApplication
public 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的属性。