|
swagger学习笔记
什么是swagger
swagger是通过注解自动生成json或者yml文件,进而解析成api文档的一个组件,利用swagger-ui生成在线的可以实时跟新的api文档,方便前后端和协同开发.
基本配置
@Configuration
public class SwaggerConfig {
/**
* Doctet是swagger的 全局配置对象
* @return
/
@Bean
public Docket getDocket(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
//api帮助文档的描述信息
ApiInfo apiInfo = new ApiInfoBuilder()//构建者模式
.contact(//配置swagger文档主题内容
new Contact(“swagger开发文档”,//文档的发布者名称
“http://”,//文档发布者的网站信息
“123.com”))//文档发布者的邮箱
.description(“swager学习描述”)//文档的描述
.title(“swagger学习文档”)//文档的标题
.version(“1.1”)//文档的版本
.build();
//给docket上下文配置api描述信息
docket.apiInfo(apiInfo);
docket.select()//获取docket中的选择器,的那会类型是ApiSelectorBuilder,构建选择器:如:扫描什么包的注解
.apis(
Predicates.not(//取反 true–false false-true
RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解时返回true
MyAnnotation4Swagger.class//方法的上的注解类
)
))
.apis(RequestHandlerSelectors.basePackage(“com.liu.controller”))//设定早苗那个包包含子包
.paths(
Predicates.or(//以下三个里面的任何一个都可以
PathSelectors.regex("/swagger/."),//使用正则表达式,约束生成API文档的路径地址,控制器里面只有swagger路径的才会生成文档,其他的不生成表示0-n个
PathSelectors.regex("/swagger2/."),
PathSelectors.regex("/.*")
)
)
.build();//重新构建Docket对象
//等价于
// docket.select()//获取docket中的选择器,的那会类型是ApiSelectorBuilder,构建选择器:如:扫描什么包的注解
// .apis(
// Predicates.and(
// Predicates.not(//取反 true–false false-true
// RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解时返回true
// MyAnnotation4Swagger.class//方法的上的注解类
// )
// ),
// RequestHandlerSelectors.basePackage(“com.liu.controller”)
// )
// )
.apis(RequestHandlerSelectors.basePackage(“com.liu.controller”))//设定早苗那个包包含子包
// .build();//重新构建Docket对象
return docket;
}
}
controller类
/**
-
@Api—描述当前类型生成帮助文档的信息 -
属性: -
tags:给当前类型定义别名,有几个别名就会在ui视图里面生成几个菜单 -
description:给当前类型生成的帮助文档一个描述信息
*/
@RestController
@RequestMapping("/swagger")
@Api(tags = {“mycontroller”,“swagger学习控制器”},description = “测试Api文档的描述信息”)
public class HelloController {
@RequestMapping("/entity")
public Myentity entity(){
return new Myentity();
}
// @ApiImplicitParam(name =“m”,value = “参数m的描述”,required = false,paramType = “字符串”,dataType = “名值对”)
@ApiImplicitParams(value = {
@ApiImplicitParam(name =“m”,value = “参数m的描述”,required = false,paramType = “字符串”,dataType = “名值对”),
@ApiImplicitParam(name=“n”,value = “n的描述”,required = true,paramType = “字符串(string)”,dataType = “名值对”)
})
@GetMapping("/test")
public String test(String m, String n){
return “test”;
} /**
- @ApiIgnore 当前注解描述的方法或者类不生成api帮助文档, 和前面写的自定义注解功能差不多
- @return
*/
@ApiIgnore
@GetMapping("/get")
public String get(){
return “get”;
}
@PostMapping("/post")
//为方法做描述信息
@ApiOperation(value=“post请求方法,做新增需求”,notes = “学习使用post请求的方法”)
public String post(
@ApiParam(name = “用户名(a)”,value = “用户新增提交的用户名”,required = true) String a,
@ApiParam(name=“密码 “,value = “新增用户的密码”,required = true) String b){
return “post”;
}
@MyAnnotation4Swagger
@RequestMapping(”/req”)
public String map( int m){
return “req”;
}
}
entity
/**
-
@Apimodel —描述一个实体类,这个实体成功任何一个生成api文档的方法的返回值类型的时候,次注解被解析
*/
@ApiModel
public class Myentity implements Serializable {
@ApiModelProperty(value = “主键”,name=“主键(id)”,required = false,example = “1”,hidden = false)
private Integer id;
@ApiModelProperty(value = “用户名”,name=“用户名(username)”,required = true,example = “张三”,hidden = false)
private String username;
@ApiModelProperty(value = “密码”,name=“密码(password)”,required = true,example = “123456”,hidden = false)
private String password; public Myentity() {
}
|