Swagger：API框架

Swagger：API框架

Swagger简介

  • 号称世界上最流行的Api框架;

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

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

  • 支持多种语言: Java, Php...

Swagger官网: https://swagger.io/

在项目使用Swagger需要springbox;

  • swagger2
  • ui

SpringBoot集成Swagger

  1. 新建一个Spring Boot，web项目

  2. 导入相关依赖

    <!--swagger2的依赖-->
<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

  4. 配置Swagger在config包下写配置类SwaggerConfig

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

  5. 测试运行：http://localhost:8080/swagger-ui.html

    ![img](file:///C:\Users\admin\AppData\Roaming\Tencent\Users\424292697\QQ\WinTemp\RichOle\OXMI84HT]8B0P[Y{QX~{YTH.png)

配置Swagger信息

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {
    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());//把下面配置的swagger信息加进去
    }
    //配置swagger信息=apiInfo
    private ApiInfo apiInfo () {
        //作者信息,作者名，路径，邮箱
        Contact contact = new Contact("ys", "https://www.cnblogs.com/yu-si", "");
        return new ApiInfo(
                "ys的SwaggerAPI文档",    //标题
                "yuansi",           	//描述
                "v1.0",                 //版本
                "urn:tos",    			//服务组织路径
                // DEFAULT_CONTACT
                contact,                //作者信息
                "Apache 2.0",           //开源版本号
                "http://www.apache.org/licenses/LICENSE-2.0",//开源版本号路径
                new ArrayList());
    }
}

测试运行：http://localhost:8080/swagger-ui.html的页面

img

配置扫描接口及开关

配置扫描接口：

.apis(RequestHandlerSelectors.basePackage("com.ys.controller"))一般用这个

 //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller")  一般用这个
                //any()：扫描全部RequestHandlerSelectors.any()
                //none()：不扫描RequestHandlerSelectors.none()
                //withMethodAnnotation:扫描方法上有GetMapping注解			 RequestHandlerSelectors.withClassAnnotation(GetMapping.class)
                //withClassAnnotation:扫描类上有RestController注解RequestHandlerSelectors.withClassAnnotation(RestController.class)
                .build();
    }

配置过滤接口：

.paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口 一般用这个

    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                //paths()过滤路径
                .paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口  一般用这个
                //PathSelectors.none()不过滤
                //PathSelectors.any()过滤全部
                //PathSelectors.regex()
                .build();
    }

配置swagger开关：

.enable(true)

    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//把下面配置的swagger加进去
                .enable(false)//是否启用Swagger,false不能再浏览器访问，默认true.
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller")  一般扫描包
                .apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
                //paths()过滤路径
                .paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口  一般用这个
                .build();
    }

swagger配置:

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {
    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//把下面配置的swagger加进去
                .enable(false)//是否启用Swagger,false不能再浏览器访问，默认true.
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller")  一般扫描包
                //any()：扫描全部RequestHandlerSelectors.any()
                //none()：不扫描RequestHandlerSelectors.none()
                //withMethodAnnotation:扫描方法上有GetMapping注解			 RequestHandlerSelectors.withClassAnnotation(GetMapping.class)
                //withClassAnnotation:扫描类上有RestController注解RequestHandlerSelectors.withClassAnnotation(RestController.class)
                .apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
                //paths()过滤路径
                .paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口  一般用这个
                //PathSelectors.none()不过滤
                //PathSelectors.any()过滤全部
                //PathSelectors.regex()
                .build();
    }
    
    
    //配置swagger信息=apiInfo
    private ApiInfo apiInfo () {
        //作者信息,作者名，路径，邮箱
        Contact contact = new Contact("ys", "https://www.cnblogs.com/yu-si", "");
        return new ApiInfo(
                "ys的SwaggerAPI文档",    //标题
                "yuansi",           //描述
                "v1.0",                 //版本
                "urn:tos",    //服务组织路径
                // DEFAULT_CONTACT
                contact,                           //作者信息
                "Apache 2.0",           //开源版本号
                "http://www.apache.org/licenses/LICENSE-2.0",//开源版本号路径
                new ArrayList());
    }
}

Swagger在一个环境使用

我只希望我的Swagger在生产环境中使用，在发布的时候不适用？

三个application.properties文件，不同文件不同端口不同配置和参数

application.properties配置：
激活dev开发环境---spring.profiles.active=dev
激活prod开发环境---spring.profiles.active=prod

application-dev.properties开发环境配置
application-prod.properties正式环境配置

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

  • 注入enable（flag）

  •  @Bean
    public Docket docket(Environment environment){      //这个接口import org.springframework.core.env.Environment;
        //设置要显示的Swagger环境,
        // dev则开启Swagger环境,否则不开启,可以放多个Profiles.of("dev","test");
        Profiles profiles = Profiles.of("dev");
        //获得项目的环境,通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);//监听
        //getActiveProfiles();获得一个激活的文件
        //getDefaultProfiles();获得一个默认的文件

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//把下面配置的swagger加进去
                .enable(flag)//是否启用Swagger,如果是指定的环境则启用Swagger
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller")  一般用这个
                .apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
                //paths()过滤路径
                .paths(PathSelectors.ant("/ys/**"))//只扫描ys下的接口  一般用这个
                .build();
    }

全代码

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {
    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){      //这个接口import org.springframework.core.env.Environment;
        //设置要显示的Swagger环境,
        // dev则开启Swagger环境,否则不开启,可以放多个Profiles.of("dev","test");
        Profiles profiles = Profiles.of("dev");
        //获得项目的环境,通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);//监听
        //getActiveProfiles();获得一个激活的文件
        //getDefaultProfiles();获得一个默认的文件

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//把下面配置的swagger加进去
                .enable(flag)//是否启用Swagger,false不能再浏览器访问，默认true.
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller")  一般用这种
                //any()：扫描全部RequestHandlerSelectors.any()
                //none()：不扫描RequestHandlerSelectors.none()
                //withMethodAnnotation:扫描方法上有GetMapping注解RequestHandlerSelectors.withClassAnnotation(GetMapping.class)
                //withClassAnnotation:扫描类上有RestController注解RequestHandlerSelectors.withClassAnnotation(RestController.class)
                .apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
                //paths()过滤路径
                .paths(PathSelectors.ant("/ys/**"))//只扫描ys下的接口  一般用这个
                //PathSelectors.none()不过滤
                //PathSelectors.any()过滤全部
                //PathSelectors.regex()
                .build();
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo () {
        //作者信息,作者名，路径，邮箱
        Contact contact = new Contact("ys", "https://www.cnblogs.com/yu-si", "");
        return new ApiInfo(
                "ys的SwaggerAPI文档",    //标题
                "yuansi",           //描述
                "v1.0",                 //版本
                "urn:tos",    //服务组织路径
                // DEFAULT_CONTACT
                contact,                           //作者信息
                "Apache 2.0",           //开源版本号
                "http://www.apache.org/licenses/LICENSE-2.0",//开源版本号路径
                new ArrayList());
    }
}

配置API文档分组

.groupName("ys")

如何配置多个分组；多个Docket示例即可

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

afsasfa

asdf

接口注释

实体类注释

controller层

@RestController
public class HelloController {
    //只要我们的接口中，返回值中存在实体类，他就会被扫描到swagger中
    @PostMapping(value = "/user")
    public User user() {
        return new User();
    }
}

pojo层

@ApiModel("用户实体类")//swagger实体类Model文档注释
public class User {
    @ApiModelProperty("用户名")//swagger字段Model文档注释,private修饰的swagger获取不到
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

swagger页面注释显示

gaga

控制层注释

@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello() {
        return "hello";
    }
    //operation接口,不是放在类上的，是方法
    @ApiOperation("HelloController控制类")
    @PostMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username) {
        return "hello" + username;
    }
}

swagger页面注释显示

asd

小结

  1. 我们可以通过Swagger给一些比较难理解的属性或者接口， 增加注释信息
  2. 接口文档实时更新
  3. 可以在线测试

Swagger是一个优秀的工具,几乎所有大公司都有使用它

[注意点]在正式发布的时候，关闭Swagger! ! !出于安全考虑。而且节省运行的内存;

posted @   渝思  阅读(238)  评论(0)  编辑  收藏  举报
（评论功能已被禁用）
编辑推荐：
· Linux系列：如何用heaptrack跟踪.NET程序的非托管内存泄露
· 开发者必知的日志记录最佳实践
· SQL Server 2025 AI相关能力初探
· Linux系列：如何用 C#调用 C方法造成内存泄露
· AI与.NET技术实操系列（二）：开始使用ML.NET
阅读排行：
· 无需6万激活码！GitHub神秘组织3小时极速复刻Manus，手把手教你使用OpenManus搭建本
· C#/.NET/.NET Core优秀项目和框架2025年2月简报
· Manus爆火，是硬核还是营销？
· 终于写完轮子一部分：tcp代理 了，记录一下
· 【杭电多校比赛记录】2025“钉耙编程”中国大学生算法设计春季联赛（1）
点击右上角即可分享
微信分享提示