使用swagger2|使用swagger2 生成API文档使用swagger2生成API文档

1.引入依赖

这里用的是2.7.0版本

io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0

上线的时候可能需要找到所有依赖的jar包,如下图

文章图片

2.swagger配置类

@Configuration @EnableSwagger2 public class Swagger2 {/** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现， * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("cn.wx.swagger"))//配置扫描的包路径 .paths(PathSelectors.any()) .build(); }/** * 创建该API的基本信息（这些基本信息会展现在文档页面中） * 访问地址：http://项目实际地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("这是标题- API文档")//标题 .description(" 此处填写标题描述~~~~~~~~~~~~~~~")//标题描述 .termsOfServiceUrl("https://www.baidu.com") .contact("LYC")//创建者 .version("1.0")//版本 .build(); } }

文章图片

3.接口使用相关注解示例

@API :用在类上,标识这个类是swagger的资源
value:
description:接口描述

文章图片

文章图片
@ApiOperation：注解来给API增加方法说明。
value:方法描述
notes:提示信息

文章图片

文章图片
@ApiImplicitParams : 用在方法上包含一组参数说明。

@RequestMapping(value = "https://www.it610.com/byname", method = RequestMethod.GET) @ResponseBody @ApiImplicitParams({ @ApiImplicitParam(paramType = "query",name= "username" ,value = "https://www.it610.com/article/用户名",dataType = "string",required = true,defaultValue = "https://www.it610.com/article/张三"), @ApiImplicitParam(paramType = "query",name= "age" ,value = "https://www.it610.com/article/年龄",dataType = "int",required = true), @ApiImplicitParam(paramType = "query",name= "address" ,value = "https://www.it610.com/article/地址",dataType = "string",required = true) }) @ApiOperation(value = "https://www.it610.com/article/通过用户名获取用户信息", notes="返回用户信息") public ResponseEntity getUserByUserName(HttpServletRequest request, String username, Integer age, String address) { StuUser stuUser = new StuUser(); stuUser.setAddress(address); stuUser.setAge(age); stuUser.setName(username); return new ResponseEntity(stuUser, HttpStatus.OK); }

文章图片

@ApiImplicitParam：用来注解来给方法入参增加说明。

paramType:指定参数放在哪个地方	header:请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path:以地址的形式提交数据,请求参数的获取：@PathVariable body：以流的形式提交,仅支持POST（不常用） form:以form表单的形式提交,仅支持post（不常用）
name:参数名
value：说明参数的描述
dataType：参数类型	只做标志说明
required：参数是否必须传	true或false
defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

文章图片

文章图片
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
l code：数字，例如400
? l message：信息，例如"请求参数没填好"
? l response：抛出异常的类
@ApiModel：用于类，表示对类进行说明，用于参数用实体类接收；
@ApiModelProperty：用于方法，字段，表示对model属性的说明或者数据操作更改

文章图片

文章图片