swagger入门

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() {
  }