SpringBoot整合Swagger

SpringBoot整合Swagger
强烈推介IDEA2020.2破解激活,IntelliJ IDEA 注册码,2020.2 IDEA 激活码

目录

1.Swagger介绍
2.SpringBoot中快速使用Swagger
3.Swagger配置
4.Swagger通过注解描述文档

1.Swagger介绍

Swagger诞生的背景:

相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。再次条件下,Swagger就孕育而生了😄。

Swagger官网地址:https://swagger.io/
在这里插入图片描述
Swagger简介:

  • Swagger号称世界上最流行的Api框架;
  • Swagger是Restful Api 文档在线自动生成工具,Api文档与Api定义同步更新
  • 支持在线测试Api接口,相当于自带了一个postman工具;
  • 支持多种语言。

2.SpringBoot中快速使用Swagger

导入依赖:

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

初步简单配置Swager:

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   
    
}

这样简单配置后就可以是使用Swagger了,访问Swagger提供的UI界面http://localhost:8081/swagger-ui.html ,地址为:项目ip:端口号/swagger-ui.html。可以看到在UI界面显示了文档基础信息、控制器、控制器下对应的Api信息,实体类等信息。点击Api还可以进行在线请求测试。
在这里插入图片描述

3.Swagger配置

Swagger的配置相对来说也比较简单,我们只需要配置一个Swagger的Docket实例即可。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   

    @Bean
    public Docket docket(Environment environment) {
   
        //判断当前环境同允许的环境是否匹配
        boolean enableSwagger = environment.acceptsProfiles(Profiles.of("dev","test"));
        //返回Docket实例
        return new Docket(DocumentationType.SWAGGER_2)
                //Api组名,我开发的是User模块,则可命名为UserApi;其他人开发的其他模块则以其他的组名配置新的Docket
                .groupName("UserApi")
                //是否使用Swagger,应该在开发环境使用,生产环境时不使用
                .enable(enableSwagger)
                //Api的Base路径,所有Api的前缀
                .pathMapping("/")
                //配置Api文档信息
                .apiInfo(apiInfo())
                .select()
                //配置要扫描的Api:controller包下的所有Api
                .apis(RequestHandlerSelectors.basePackage("cn.korb1n.springbootproject.controller"))
                //配置要扫描的路径:所有路径
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
   
        return new ApiInfoBuilder()
                .title("Korbin的Api文档")
                .description("这是这个Api文档的描述")
                .version("文档版本1.0")
                .termsOfServiceUrl("http://www.baidu.com?wd=服务条款网址")
                .contact(new Contact("Korbin","http://www.korbin.top","86744316@qq.com"))
                .license("商标品牌")
                .licenseUrl("http://www.baidu.com?wd=品牌官网")
                .extensions(new ArrayList<>()).build();
    }

}

在这个Docket的Bean中,配置了Swagger要映射路径、要扫描的接口的位置和要使用Swagger的环境;在apiInfo中,主要配置了一下Swagger2文档UI界面网站的信息,如网站的title,网站的描述,联系人的信息,使用的协议等等。

4.Swagger通过注解描述文档

配置好Swagger后,分类生成了Api接口,乍一看上去这个Api文档基本成型,但还缺少了对接口和实体类等的描述和注释,不然开发人员单看着这些接口,也很难知道接口的功能。

在Swagger中我们可以通过其提供的注解,非常便捷的给需要的地方加上描述,详细注解如下表:

注解 说明 参数
@Api 作用于类,表示这个类是个Controller控制器 value:类描述; tags:同样表示描述,但是值为数组
@ApiOperation 作用于方法,表示一个http请求的操作 value:方法描述;notes:内容提示;tags:可以重新分组(视情况而用)
@ApiParam http请求方法的参数,字段说明;表示对参数添加元数据 name:参数名;value:参数说明;required:是否必填
@ApiModel 作用于类,表示这是一个实体类 value:实体类对象名;description:描述
@ApiModelProperty 用于方法、字段; 表示对model属性的说明或操作说明 value:字段说明;name:重写属性名字;dataType:重写属性类型;required:是否必须填写;example:举例说明;hidden:隐藏
@ApiIgnore 用于类或者方法上,可以不被swagger显示在页面上
@ApiImplicitParam 用于方法(表示单个参数) name:参数名;value:参数说明;dataType:数据类型;paramType:参数类型;example:举例说明
@ApiImplicitParams 用于方法(表示多个参数),包含多个 @ApiImplicitParam @ApiImplicitParam

示例:

@ApiModel(value = "User",description = "用户信息实体类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
   
    @ApiModelProperty(value = "用户id",example = "100000")
    @TableId(type = IdType.AUTO)
    private Long id;
}


@Api(tags = "用户控制器")
@RestController
public class UserController {
   

    @Autowired
    private UserMapper userMapper;

    @ApiOperation(value = "按照id查找用户")
    @GetMapping("/user")
    public User findById(@ApiParam(name = "id",value = "用户id") Long id){
   
        return userMapper.selectById(id);
    }
}

可以看到Api文档的描述信息发生改变了:
在这里插入图片描述
注意:如果例如上述的id字段为Long,但是在注解中没有写明example参数,会默认id的值为空字符串,就会报错:
在这里插入图片描述

本文来源MrKorbin,由架构君转载发布,观点不代表Java架构师必看的立场,转载请标明来源出处:https://javajgs.com/archives/25262

发表评论