Swagger使用教程以及常用注解

第一步：引入依赖，swagger2和swagger-ui两个依赖。

 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第二步：也是核心步骤：配置swagger配置类：
【注意点】：配置类的注解@Configuration，开启swagger注解@EnableSwagger2 别忘了

@Configuration
@EnableSwagger2 //开启swagger2自动生成api文档的功能
public class AppSwaggerConfig {
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().title("文档接口头部信息").description("描述说明文档").termsOfServiceUrl("http://www.baidu.com")
                .version("v1.0").build();
    }
    @Bean
    public Docket createRestApi(){
    //必填项，类型是三种SWAGGER_12  SWAGGER_2  SPRING_WEB
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .select()
                //常用扫描controller包：注意包路径，其他形式看源码
                .apis(RequestHandlerSelectors.basePackage("com.yyy.controller"))
                //过滤  类型any  none regex ant
                .paths(PathSelectors.any())
                .build();
    }
}

第二步：可以直接写controller进行测试

@RestController
@RequestMapping("/user")
@Api(tags = "第一个Swagger测试")
public class UserController {
 	@ApiOperation("测试方法hello")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @GetMapping("/hello")
    public String getHello(String name){
        return "OK" + name;
    }
}

这样一个简单的测试就完成了,很简单。默认端口http://localhost:8080/swagger-ui.html

接下来：说一下常用的注解，第一个controller使用到的

@Slf4j //日志
@Api(tags = "第一个Swagger测试") //添加在类上：声明一个模块的名称。

@ApiOperation("测试方法hello") //添加在方法上：对这个方法的描述，测试什么的

@ApiImplicitParam(name = "name", value = "姓名", required = true)//添加在方法上：参数+说明

 @ApiImplicitParams(
 {@ApiImplicitParam(name = "username", value = "用户名", required = true),
  @ApiImplicitParam(name = "password", value = "密码", required = true)})
//添加在方法上，用于多个参数{ }包裹

@GetMapping("/hello")//这里所有的请求，都是restful风格，注意一下！！！！

还有个用于实体类的注解：常用的两个

@ApiModel("测试实体")//添加在实体类上：在models里面显示，实体参数
@ApiModelProperty(value = "主键")//添加在属性上：对属性的说明

还有个可能用到的就是分组：

@Bean
public Docket createA() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
@Bean
public Docket createB() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
@Bean
public Docket createC() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

说一下它的好处：
① 我们可以通过swagger给一些比较难理解的属性或者接口，增加注释信息
② 接口文档实时更新
③ 可以在线测试
swagger是一个优秀的工具，几乎所有大公司都会使用它
【注意点】在正式发布的时候，出于安全考虑，我们需要关闭swagger！！！！还可以节省内存。