Swagger

Swagger

SpringBoot集成

1、依赖

• swagger2
• ui

<!--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>

2、业务

3、Config配置

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


}

• 访问：localhost:8089**/swagger-ui.html**

---

配置Swagger信息

• Config

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

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

    //配置Swagger信息的info
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("辰", "", "");
        return new ApiInfo(
                "Chen的SwaggerAPI文档【标题】",
                "Api Documentation【描述】",
                "1.0【版本】",
                "urn:tos【组织】",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

---

Swagger配置扫描接口

• Docket.select()

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置了Swagger 的 Docket 的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");//为dev环境才进行test
        //获取项目的环境（通过environment.acceptsProfiles判断是否处于自己设定的环境当中）
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("辰呀")  //API分组
                .enable(flag)  //是否启用Swagger，如果为false，则Swagger不能在浏览器中访问
                .select()
                //RequestHandlerSelectors ,配置要扫描接口的方式
                    // .basePackage("com.chen.swagger.controller") 扫描指定的包 【*】
                    // .any()  :扫描全部
                    // .none()  :不扫描
                    // .withClassAnnotation()  :扫描 类 上的注解，参数是一个注解的反射对象（GetMapping.class）
                    // .withMethodAnnotation()  :扫描 方法 上的注解（RestController.class）
                .apis(RequestHandlerSelectors.basePackage("com.chen.swagger.controller"))
                // paths:过滤什么路径
                //.paths(PathSelectors.ant("/chen/**"))
                .build();
    }

    //配置Swagger信息的info
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("辰", "", "");
        return new ApiInfo(
                "Chen的SwaggerAPI文档【标题】",
                "Api Documentation【描述】",
                "1.0【版本】",
                "urn:tos【组织】",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

Swagger在生产环境中使用，发布的时候不使用

• 判断是否生产环境 flag = false
• 注入enable（flag）

判环境实现Swagger

• application【默认】

server.port=8089
#选择哪套环境
spring.profiles.active=dev  

• application-dev【生产环境】

• application-pro【f发布环境】

配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置了Swagger 的 Docket 的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");//为dev环境才进行test
        //获取项目的环境（通过environment.acceptsProfiles判断是否处于自己设定的环境当中）
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("辰呀")  //API分组
                .enable(flag)  //是否启用Swagger，如果为false，则Swagger不能在浏览器中访问
                .select()
                //RequestHandlerSelectors ,配置要扫描接口的方式
                    // .basePackage("com.chen.swagger.controller") 扫描指定的包 【*】
                    // .any()  :扫描全部
                    // .none()  :不扫描
                    // .withClassAnnotation()  :扫描 类 上的注解，参数是一个注解的反射对象（GetMapping.class）
                    // .withMethodAnnotation()  :扫描 方法 上的注解（RestController.class）
                .apis(RequestHandlerSelectors.basePackage("com.chen.swagger.controller"))
                // paths:过滤什么路径
                //.paths(PathSelectors.ant("/chen/**"))
                .build();
    }
     
     //配置Swagger信息的info
     
}

配置API文档分组

• .groupName(“ “)

return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("辰呀")  //API分组

配置多个分组：多个Docket实例

@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");
}

---

文档注释注解

@API

• 文档注释

实体类

• 实体类上：@ApiModel(“注释”)
• 属性上：@ApiModelProperty(“注释)

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

接口

• 接口上： @ApiOperation(“user接口”)
• 属性上：@ApiParam(“字段”)

//放在方法上
@ApiOperation("user接口")
@PostMapping("/hello")
public User user(@ApiParam("用户名")String username){
    return new User();
}