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

SpringBoot09：Swagger

news 2025/6/28 0:47:48

什么是Swagger？

①是一个API框架

②可以在线自动生成 RestFul 风格的API文档，实现API文档和API定义同步更新

③可以直接运行、在线测试 API 接口

④支持多种语言（Java、PHP等）

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

SpringBoot集成Swagger

1、新建一个springboot-web项目

2、导入依赖

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

3、编写HelloController

@RestController
public class HelloController {@RequestMapping("/hello")public String hello(){return "hello呀";}
}

4、编写Swagger配置类

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

5、测试访问：http://localhost:8080/swagger-ui.html

配置Swagger

1、配置swagger

@Configuration
@EnableSwagger2     //开启Swagger
public class SwaggerConfig {//Swagger的bean实例是Docket，所以要通过配置Docket实例来配置Swagger@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(myApiInfo());}//自定义swagger信息private ApiInfo myApiInfo(){//联系人信息Contact contact = new Contact("联系人名字", "联系人访问链接", "联系人邮箱");return new ApiInfo("标题：丘桔的SwaggerApi文档","描述：在成长","版本：v1.0","组织链接",contact,"Apache2.0","许可链接",new ArrayList<>()   //扩展);}
}

2、显示结果

Swagger配置扫描接口

    //Swagger的bean实例是Docket，所以要通过配置Docket实例来配置Swagger@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(myApiInfo()).select()/*RequestHandlerSelectors：配置要扫描接口的方式basePackage：指定要扫描的包any()：全部扫描none()：都不扫描withClassAnnotation()：扫描包含指定注解的类withMethodAnnotation()：扫描包含指定注解的方法*/.apis(RequestHandlerSelectors.basePackage("com.controller"))//paths()：过滤什么路径.paths(PathSelectors.ant("/hello/**")).build();}

配置是否启动Swagger

.enable(false)    //默认值为true

思考：怎样才能让swagger只在生产环境中使用，在发布的时候不使用？

1、设置环境

2、在docket 中获取当前环境，判断它是否为生产环境，如果是，就开启swagger

        //设置要显示的swagger环境Profiles profiles = Profiles.of("prod");//判断当前环境是不是我们设置的环境boolean flag = environment.acceptsProfiles(profiles);

配置API文档的分组

 .groupName("丘桔")

如何设置多个分组？多个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");}

实体类配置和注解

1、新建实体类

@ApiModel("给实体类加注释")
public class User {@ApiModelProperty("给属性加注释")public String username;public String password;
}

2、编写controller

    //只要controller的返回值中存在实体类，就会被扫描到swagger中@PostMapping("/user")public User user(){return new User();}@ApiOperation("给方法的注释")@GetMapping("/hello2")public String hello2(@ApiParam("给参数的注释") String username){return "hello" + username;}