Swagger快速入门

环境集成

导入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

创建配置类，开启swagger

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

}

创建controller

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

测试，访问http://localhost:8080/swagger-ui.html，可以看到页面

配置Swagger

Swagger的bean实例Docket；

//配置Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            ;
}

创建apiInfo

//配置Swagger信息apiInfo
private ApiInfo apiInfo(){
    //作者信息
    Contact contact = new Contact("无双", "https://blog.csdn.net/liuwushuang233", "11");
    return  new ApiInfo(
            "无双的SwaggerApi文档",
            "一入Java深似海",
            "v2.0",
            "https://blog.csdn.net/liuwushuang233",

            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
}

展示效果

Swagger配置扫描接口

Docket.select（）.xxx.build()

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            .select()
                .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
            .build()
            ;
}

RequestHandlerSelectors.xxx方法如下：

basePackage(final String basePackage) // 根据包路径扫描接口
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)

paths()过滤请求

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            .select()
                .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
                .paths(PathSelectors.ant("/liu/**"))
            .build()
                ;
}

其余选值

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

配置是否启动swagger

.enable(false)//默认为true若为false则无法启动swagger

 @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)
            .select()
                .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
              //  .paths(PathSelectors.ant("/liu/**"))
            .build()
                ;
}

效果：

场景：

swagger在test环境使用，发布时候不使用

1. 判断是否是生产环境
2. 注入enable值

使用Environment

application.properties

spring.profiles.active=test

application-dev.properties

server.port=8081

application-test.properties

server.port=8082

config

    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles=Profiles.of("test");
        //获取项目的环境,通过environment.acceptsProfiles判断是否处于在设定环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
            .select()
                .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
              //  .paths(PathSelectors.ant("/liu/**"))
            .build()
                ;
}

除了8082端口都不会显示

配置Api文档分组

.groupName

    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("无双")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
              //  .paths(PathSelectors.ant("/liu/**"))
            .build()
                ;
}

配置多个分组

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}  
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

效果：

实体类配置：

创建实体类并绑定

//只要接口中，返回值有实体类，他就会被扫描到swagger
@PostMapping("/name")
public User user(){
    return new User();
}

@ApiModel给文档添加注释

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

接口api

@GetMapping(value = "/hello2")
@ApiOperation("hello2请求")
public String hello(@ApiParam("用户名") String username){
    return "hello"+username;
}

使用测试

Try it out 传入值点击Execute就可以测试

注意：

正式发布的时候，关闭Swagger，节省内存，出于安全考虑。