【SpringBoot高级篇】SpringBoot集成Swagger2在线接口文档

李熠漾

已于 2023-01-07 21:39:30 修改

阅读量543

点赞数

分类专栏： # SpringBoot 文章标签： java spring boot

于 2021-05-03 10:11:59 首次发布

本文链接：https://blog.csdn.net/qq_45297578/article/details/116372988

版权

SpringBoot 专栏收录该内容

84 篇文章 40 订阅

订阅专栏

【SpringBoot高级篇】SpringBoot集成Swagger2在线接口文档

1. 手写文档存在的问题
2. 使用 Swagger 解决问题
3. Maven
4. 配置 Swagger2
- 生成接口文档的方式
5. 启用 Swagger2
- 微服务场景下启动Swagger2
6. 使用 Swagger2
- 6.1 Swagger 注解说明
7. 访问 Swagger2

1. 手写文档存在的问题

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如：Postman
接口文档太多，不好管理

2. 使用 Swagger 解决问题

Swagger 也就是为了解决这个问题，当然也不能说 Swagger 就一定是完美的，当然也有缺点，最明显的就是代码植入性比较强。

3. Maven

增加 Swagger2 所需依赖，pom.xml 配置如下：

<!-- Swagger2 Begin -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>
<!-- Swagger2 End -->

或者swagger-spring-boot-starter包含了上面的依赖

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.1.RELEASE</version>
</dependency>

4. 配置 Swagger2

创建一个名为 Swagger2Config 的 Java 配置类，代码如下：

@Configuration
@EnableSwagger2 //或者写在启动类上
public class Swagger2Config {

    @Value("${swagger.enable}")
    private boolean swaggerEnable;
    //是否允许显示swagger。此值可在application.yml中设定。
    //作为开关，可在生产环境和开发环境打开或关闭，简便易行。

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .apiInfo(apiInfo())
                .select()
          		//.apis(RequestHandlerSelectors.basePackage("com.cdwm.mrp.controller")) 指定扫描包
 				//指定带类Api注解就扫描
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

     private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("客户记录API文档")
                .description("客户记录API文档")
                .version("1.0.0")
                .build();
    }
}

生成接口文档的方式

指定包扫描生成swagger文档

@Bean
public Docket createRestApi() {
   return new Docket(DocumentationType.SWAGGER_2)
           .enable(swaggerEnable)
           .apiInfo(apiInfo())
           .select()
           .apis(RequestHandlerSelectors.basePackage("cn.zysheep.controller")) 
           .paths(PathSelectors.any())
           .build();
}

指定类上标记注解扫描生成swagger文档

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(swaggerEnable)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
            .paths(PathSelectors.any())
            .build();
}

指定方法上标记注解扫描生成swagger文档

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(swaggerEnable)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build();
}

按请求路径分组创建多个Swagger2文档

/**
 * Swagger2配置信息
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();

    }

    @Bean
    public Docket adminApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("zysheep", "http://zysheep.cn", "zysheep@126.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("zysheep", "http://zysheep.cn", "zysheep@126.com"))
                .build();
    }


}

5. 启用 Swagger2

在启动类加 @EnableSwagger2或swagger配置类上加注解表示开启 Swagger，不加会报错

@EnableSwagger2
public class ServiceAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceAdminApplication.class, args);
    }
}

微服务场景下启动Swagger2

在微服务场景下，因为我们有多个服务都需要使用swagger2，我们一般会把swagger2抽取为另外的一个配置服务，当那个服务用到了就把坐标导入即可。
比如：在commons下的service-util为swagger2的配置，现在订单服务需要使用swagge2在线生成文档接口。
在这里插入图片描述
swagger2配置

订单微服务启动类配置，使用@ComponentScan扫描包cn.zysheep，切记不能扫描cn.zysheep.config，不然会找不到订单服务的bean，原因是订单服务启动类在cn.zysheep.order中而你却只扫描cn.zysheep.config,所以扫描不到bean或者@Import导入配置文件类

@ComponentScan(basePackages = {"cn.zysheep"})
//@Import({Swagger2Config.class})

在这里插入图片描述

6. 使用 Swagger2

在Controller中增加Swagger2 相关注解，代码如下：

@ApiOperation(value = "管理员分页查询")
@ApiImplicitParams({
        @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "pageSize", value = "笔数", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "tbSysUserJson", value = "管理员对象 JSON 字符串", required = false, dataTypeClass = String.class, paramType = "json")
})
@RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
public String  page(
        @PathVariable(required = true) int pageNum,
        @PathVariable(required = true) int pageSize,
        @RequestParam(required = false) String tbSysUserJson
) throws Exception {

    return "Hello Swagger2";
}

6.1 Swagger 注解说明

注解	说明
@Api	用在请求的类上，例如Controller，表示对类的说明
@ApiModel	用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty	用在属性上，描述响应类的属性
@ApiOperation	用在请求的方法上，说明方法的用途、作用
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

Swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述 Controller 的作用

 tags="说明该类的作用"
 value="该参数没什么意义，所以不需要配置"
 
@Api(tags="APP用户注册Controller")

@ApiOperation：描述一个类的一个方法，或者说一个接口

value="说明方法的作用"
notes="方法的备注说明"

@ApiOperation(value="用户注册",notes="手机号、密码都是必输项，年龄随边填，但必须是数字")

@ApiParam：单个参数描述
@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数

name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
   · header --> 请求参数的获取：@RequestHeader
   · query --> 请求参数的获取：@RequestParam
   · path（用于restful接口）--> 请求参数的获取：@PathVariable
   · body（不常用）
   · form（不常用）    
dataType：参数类型，默认String，其它值dataType="Integer"       
defaultValue：参数的默认值


@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer"), 
    @ApiImplicitParam(name="token", value="token", dataType="String", paramType="header",required = true)	      
})

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{
 
    @ApiModelProperty(value = "是否成功")
    private boolean success=true;
    @ApiModelProperty(value = "返回对象")
    private Object data;
    @ApiModelProperty(value = "错误编号")
    private Integer errCode;
    @ApiModelProperty(value = "错误信息")
    private String message;
 
    /* getter/setter */
}

@ApiResponse：HTTP 响应其中 1 个描述

code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

@ApiOperation(value = "select1请求",notes = "多个参数，多种的查询参数类型")
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})

@ApiResponses：HTTP 响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError：发生错误返回的信息

7. 访问 Swagger2

访问地址：http://ip:port/swagger-ui.html
在这里插入图片描述

李熠漾

关注

0
点赞
踩
5

收藏

觉得还不错? 一键收藏
打赏
0
评论
【SpringBoot高级篇】SpringBoot集成Swagger2在线接口文档

SpringBoot整合Swagger21. 手写文档存在的问题2. 使用 Swagger 解决问题3. Maven4. 配置 Swagger24.1 启用 Swagger24.2 使用 Swagger24.3 Swagger 注解说明4.4访问 Swagger21. 手写文档存在的问题文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。接口返回结果不明确不能直接在线测试接口，通常需要使用工具，比如：Postman接口文档太多，不好管理2. 使用 Swagger 解决问题
复制链接

扫一扫