当前位置：首页 > news >正文

SpringBoot整合Swagger

news 2025/7/4 14:45:04

一、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 {@Beanpublic 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实例@Beanpublic Docket controllerApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}//配置swagger信息=apiinfoprivate 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扫描接口

@Beanpublic 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()

  @Beanpublic 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、读取生产环境

@Beanpublic 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()

@Beanpublic 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实例即可

@Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("B");}@Beanpublic 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("成功");}