💘10分钟,6个点,SpringBoot集成丝袜哥(Swagger)整的明明白白💘

举报
XiaoLin_Java 发表于 2022/01/31 17:50:21 2022/01/31
【摘要】 1. 什么是Swagger相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只...

1. 什么是Swagger

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

发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。

2. Swagger注解详解

2.1 @Api

@Api 用在类上,说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源

tags:接口说明,可以在页面中显示。可以配置多个,当配置多个的时候,在页面中会显示多个接口的信息。description:对tags 进行描述说明

@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述

在这里插入图片描述

2.2 @ApiModel

@ApiModel 用在类上,表示对类进行说明,用于实体类中的参数接收说明

@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {

    @ApiModelProperty(value = "账号")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}

在这里插入图片描述

2.3 @ApiModelProperty

@ApiModelProperty() 用于字段,表示对 model 属性的说明

package com.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {

    @ApiModelProperty(value = "账号")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}

在这里插入图片描述

2.4 @ApiParam

@ApiParam 用于 Controller 中方法的参数说明

  • value:参数说明
  • required:是否必填

@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {

    @ApiOperation(value = "我的第一个swagger接口")
    @PostMapping("/swagger")
    public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
        System.out.println(request.getHeader("token"));
        return user;
    }

}

在这里插入图片描述

2.5 @ApiOperation

@ApiOperation 用在 Controller 里的方法上,说明方法的作用,每一个接口的定义

value:接口名称

@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {

    @ApiOperation(value = "我的第一个swagger接口")
    @PostMapping("/swagger")
    public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
        System.out.println(request.getHeader("token"));
        return user;
    }

}

在这里插入图片描述

2.6 @ApiResponse 和 @ApiResponses

@ApiResponse 用于方法上,说明接口响应的一些信息;@ApiResponses 组装了多个 @ApiResponse

@GetMapping("/getUser")
    @ApiOperation(value = "获取用户信息接口")
    @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
    public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
        return userService.getUserInfo(id);
    }

在这里插入图片描述

2.7 @ApiImplicitParam 和 @ApiImplicitParams

用于方法上,为单独的请求参数进行说明

@GetMapping("/getUser")
    @ApiOperation(value = "获取用户信息接口")
    @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", dataType = "string", paramType = "query", 
required = true, defaultValue = "0f09e661-7e80-4e1b-b66a-2e266bb593bf")
    })
    public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
        return userService.getUserInfo(id);
    }

在这里插入图片描述

3. 引入Swagger的jar

<!--swagger2 依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

4. 创建Swagger的配置类

package com.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration//表示这是一个配置类
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket reeateDocket(){
        List<Parameter> parameterList=new ArrayList<>();
        ParameterBuilder parameterBuilder=new ParameterBuilder();
        parameterBuilder.name("token")
                        .description("swagger调试用,模拟传入用户凭证")
                        .modelRef(new ModelRef("String"))
                        .parameterType("header").required(false);
        parameterList.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//创建该Api的基本信息(这些基本信息会展现在文档页面中)
                .select()//函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger ui来展现
                .apis(RequestHandlerSelectors.basePackage("com.controller"))//指定需要扫描的包路路径
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(parameterList)
                ;
    }
    //配置swagger的信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("spring boot2.x实战")
                .description("整合swagger")
                .termsOfServiceUrl("")
                .version("2.0")
                .build();
    }
}

5. 实体类创建

package com.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {

    @ApiModelProperty(value = "账号")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}

6. 测试类创建

package com.controller;

import com.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.HttpRequest;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {

    @ApiOperation(value = "我的第一个swagger接口")
    @PostMapping("/swagger")
    public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
        System.out.println(request.getHeader("token"));
        return user;
    }

}

7. 测试

在浏览器上输入:http://localhost:8080/swagger-ui.html

在这里插入图片描述

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。