欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

程序员文章站 2022-09-13 22:46:20
导航Swagger介绍Swagger图解SpringBoot集成Swagger UI新建SpringBoot项目整合Swagger配置Swagger信息配置Swagger扫描路径根据项目环境决定是否启用Swagger多人协作,设置不同分组的SwaggerSwagger 实体类注解@ApiModel() 用于类@ApiModelProperty() 用于方法,字段Swagger接口注解@Api()用于类@ApiOperation()用于方法@ApiIgnore() 用于类或方法上,可以不被Swagger显示...

Swagger介绍

基于RestFul 风格的文档自动生成工具;

可以实现API定义与API文档同步更新;
简化团队项目中API开发;
支持在线测试API接口;

Swagger图解

Swagger-ui界面
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

SpringBoot集成Swagger UI

新建SpringBoot项目

SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明其中Group(GruopID)一般为 域名+公司名称(例如org.apache)
Artifact(ArtifactID)一般为 项目或者模块名称 (例如swagger)
Version 表示当前项目的版本
GruopID+ArtifactID+Version 俗称坐标,可以唯一标识一个Maven项目
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明需要勾选Spring Web(或Spring Web Starter)
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明点击finish,完成
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

整合Swagger

在pom.xml中加入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> 

为方便后续配置Swagger,创建一个Swagger配置类

@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
}

启动项目,访问默认端口+/swagger-ui.html,出现如下页面,说明配置成功
例:http://localhost:8080/swagger-ui.html
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

此时只有基本的error处理器
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明当我们新增了一个/hello 的API时

@RestController
public class HelloController {
    @GetMapping(value = "/hello")//推荐写法
//@RequestMapping(value = "/hello",method = RequestMethod.GET) 等价于以上写法
    public String Hello(){
        return "hello";
    }
}

SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

配置Swagger信息

@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {

        //修改默认配置bean
        @Bean
        public Docket myDocket(){
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
        }
        private ApiInfo apiInfo(){
            return new ApiInfo(
                    "测试文档",//swagger标题
                    "A-p-i-A-p-i-A-p-i",//swagger描述
                    "v1.0",//swagger版本
                    "https://swagger.io/",//服务条款Url
                    new Contact("robot001","www.baidu.com","@email"),//联系人信息
                    "Apache 2.0",// 许可证
                    "http://www.apache.org/licenses/LICENSE-2.0",// 许可证Url
                    new ArrayList<>()
            );
        }
}

重新运行发现Swagger配置信息已更改

SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

配置Swagger扫描路径

return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())//配置Swagger信息
//          .enable(false)//是否启用Swagger---true:(默认)正常使用;false:禁用,页面显示无法加载.
			select().apis(RequestHandlerSelectors.basePackage("com.ahy.swagger.controller"))//--->设置需要扫描的包
//          .select().apis(RequestHandlerSelectors.any())//--->扫描所有
//          .select().apis(RequestHandlerSelectors.none())//--->不扫描
//          .select().apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//--->扫描带有指定注解的类
//          .select().apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))//--->扫描带有指定注解的方法
            .paths(PathSelectors.ant("/hello1/**"))//扫描指定路径
            .build();

再次运行发现空空如也,因为我们扫描了指定包和指定路径,而这个路径不存在
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

根据项目环境决定是否启用Swagger

准备工作
application.properties:设置为开发环境

spring.profiles.active=dev

application-dev.properties:设置开发环境端口

server.port=8081

application-test.properties:设置测试环境端口

server.port=8082

加载Swagger之前先判断环境,开发环境可用Swagger

@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
        //修改默认配置bean
        @Bean
        public Docket myDocket(Environment environment){
            //设置需要显示Swagger的环境
            Profiles profiles = Profiles.of("dev");
            //判断当前是否处于设定的环境中
            boolean flag = environment.acceptsProfiles(profiles);
            return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())//配置Swagger信息
            .enable(flag)//是否启用Swagger---true:正常使用;false:禁用,页面显示无法加载
            .select().apis(RequestHandlerSelectors.basePackage("com.ahy.swagger.controller"))//--->设置需要扫描的包
            .build();
        }

        private ApiInfo apiInfo(){
            return new ApiInfo(
                    "测试文档",//swagger标题
                    "A-p-i-A-p-i-A-p-i",//swagger描述
                    "v1.0",//swagger版本
                    "https://swagger.io/",//服务条款Url
                    new Contact("robot001","www.baidu.com","@email"),//联系人信息
                    "Apache 2.0",// 许可证
                    "http://www.apache.org/licenses/LICENSE-2.0",// 许可证Url
                    new ArrayList<>()
            );
        }
}

生产环境8081端口下可正常显示页面
其它环境下无法显示页面

多人协作,设置不同分组的Swagger

@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
    @Bean
    public Docket myDocket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("111");
    }
    @Bean
    public Docket myDocket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("222");
    }
    @Bean
    public Docket myDocket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("333");
    }
}

SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

Swagger 实体类注解

@ApiModel() 用于类

@ApiModelProperty() 用于方法,字段

@ApiModel(value = "用户实体类",description = "每个用户")
public class User {
    @ApiModelProperty(value = "用户名",required = true,example = "xiaoming")
    private String username;
    @ApiModelProperty(value = "用户名",required = true,example = "123456")
    private String password;
    public String getUsername() {
        return username;
    }
    public String getPassword() {
        return password;
    }
}
public class HelloController {
	//接口中的返回值包含实体类,则会显示在Model中
    //字段若是private修饰,需要有get方法才会显示该字段
    @GetMapping("/user")
    public User user() {
        return new User();//不返回user则不会显示Models
    }
}

SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

Swagger接口注解

基于RestFul的请求形式

@Api()用于类

@ApiOperation()用于方法

@ApiIgnore() 用于类或方法上,可以不被Swagger显示

@ApiParam() 用于参数前,注释该参数

@Api(tags = {"用户请求控制器"})//控制器注解
@RestController
public class HelloController {
	@ApiOperation(value = "User控制类",notes = "处理用户请求")//类名注解
    @GetMapping("/user1/{username}")
    public String user1(@ApiParam(name = "username",value = "用户名",required = true)@PathVariable String username){//参数注解
        System.out.println("username = " + username);
        return "hello:" + username;
    }
}

SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明请求测试如下
SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明

本文地址:https://blog.csdn.net/ROBOT_ADMIN/article/details/107138915