SpringBoot整合Swagger_springboot搭建swagger

目录

一、swagger介绍

二、springboot集成swagger

1、创建一个springboot-web项目

2、导入相关依赖

3、编写一个Hellow工程

4、配置swagger --->config

5、启动springboot工程

6、配置swagger信息

7、配置swagger扫描接口

8、如何设置Swagger在生产环境中使用，在发布的时候不使用?

9、配置API文档分组

10、实体类配置

---

一、swagger介绍

swagger是一个接口文档生成工具，同时提供接口测试调用的辅助功能。

RestFul Api文档在线自动生成工具=>Api文档与API定义同步更新

直接运行，可以在线测试API接口;

支持多种语言: (Java，Php....)

官网：API Documentation & Design Tools for Teams | Swagger

二、springboot集成swagger

1、创建一个springboot-web项目

2、导入相关依赖

        <!--swagger 相关依赖       -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swagger-ui.html模式        -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--doc.html模式        -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.2</version>
        </dependency>

3、编写一个Hellow工程

4、配置swagger --->config

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

5、启动springboot工程

启动后访问：

http://localhost:8080/swagger-ui.html

或者访问:http://localhost:8080/doc.html

6、配置swagger信息

方式1：

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("标题：XX公司_XXXXX系统_接口文档")
                        .description("描述：用于管理XXXXX,具体包括XXX,XXX模块...")
                        .contact(new Contact("Socks", null, null))
                        .version("版本号:1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("kgc.cn"))
                .paths(PathSelectors.any())
                .build();
    }
  
}

 方式二：

@Configuration
@EnableSwagger2
public class Swagger2Config {
 
    //配置swagger的Docket的bean实例
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置swagger信息=apiinfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("张三","","");
        return new ApiInfo(
                "swaggerAPI接口文档",
                "辛勤铸就梦想，付出就有回报。",
                "1.0",
                "https://blog.csdn.net/qi341500?spm=1000.2115.3001.5343",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

 效果：

7、配置swagger扫描接口

@Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // RequestHandlerselectors，配置要扫描接口的方式
                // basePackage:指定要扫描的包
                // any():扫描全部
                //none():不扫描
                //withclassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                // withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("cn.micro.myboot.controller"))
                //paths()过滤路径
                .paths(PathSelectors.ant("/book/**"))
                .build();
    }

配置swagger是否启动：enable()

  @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.micro.myboot.controller"))
                //.paths(PathSelectors.ant("/book/**"))
                .build();
    }

8、如何设置Swagger在生产环境中使用，在发布的时候不使用?

判断是不是生产环境flag = false

注入enable (flag;)

步骤：

1、配置多个生产环境

2、读取生产环境

@Bean
    public Docket controllerApi(Environment environment) {
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
 
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.micro.myboot.controller"))
                //.paths(PathSelectors.ant("/book/**"))
                .build();
    }

9、配置API文档分组

groupName()

@Bean
    public Docket controllerApi(Environment environment) {
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
 
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("张三")
                //enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.micro.myboot.controller"))
                //.paths(PathSelectors.ant("/book/**"))
                .build();
    }

配置多个分组，创建多个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");
    }

10、实体类配置

只要接口中返回值存在实体类，实体类就会被扫描到swagger中

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

 实体类：@ApiModel()：给实体类添加注释，@ApiModelProperty()给属性添加注释

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

 给方法添加注释：@ApiOperation()

@ApiOperation("给方法添加注释")
	@GetMapping("/user")
	public User user(){
		return new User();
	}

 给参数加注释@ApiParam() 

@ApiOperation("给方法添加注释")
	@GetMapping("/user")
	public User user(@ApiParam("给参数加注释") String username){
		return new User();
	}

 ​​​

设置请求参数：@ApiImplicitParam(name = "uid", value = "用户ID", paramType = "String")

    @ApiOperation(value = "首页")
	@ApiImplicitParam(name = "uid", value = "用户ID", paramType = "String")
	@RequestMapping(value = "login.do",method = {RequestMethod.GET,RequestMethod.POST})
	public BaseResponse<String> login(String uid){
		return RespGenerator.returnOK("成功");
	}

总结：

1、我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息

⒉、接口文档实时更新

3、可以在线测试