SpringBoot整合Swagger3.0接口文档提效神器详解

OpenApi规范

声明了用于文档规范的版本

地址:github.com/OAI/OpenAPI…

OpenApi介绍

OpenApi规范经过Reverb Technologies和SmartBear等公司多年的发展,OpenApi计划拥有该规范(捐赠之后),OpenAPI Initiative在GitHub上托管社区驱动的规范。

规范是一种与语言无关的格式,用于描述RestFul Web服务,应用程序可以解释生成的文件,这样才能生成代码、生成文档并根据其描述的服务创建模拟应用。

开放API规范(OAS)是一种无需编写实际API代码就可以记录API的方法。这是一种开放源代码格式,可以用来描述API。在此过程中,我们可以使用JSON或YAML格式

OpenAPI文档有三个必须的部分或对象,也可以增加其他模块:

1.openapi – OpenAPI规范版本的语义版本号

2.info – 有关API的元数据

3.paths – API的可用路径和操作

业界自动化接口文档生成的解决方案介绍

ApiDoc

地址:apidocjs.com/

Github:github.com/apidoc/apid…

简介:源代码中的注释直接自动生成api接口文档的工具

🌰

    /**
     * @apiGroup Product
     * @api {GET} /product/{id}  查询一个产品
     * @apiDescription 接口描述xxx
     * @apiParam {String} id 产品id(必填*)
     * @apiSuccessExample SuccessExample
     * HTTP/1.1 200
     * {
     * id: 'xxx',
     * name: 'xxx',
     * desc: 'xxxx'
     * }
     * @apiErrorExample ErrorExample
     */
    @GetMapping("/{id}")
    public Product detail(@PathVariable String id)
    {
        return JsonData.buildSuccess();
    }
复制代码

优点

  • 不侵入代码
  • 支持跨语言使用
  • 界面友好简介

缺点:依赖环境 node/npm

Swagger

地址:swagger.io/tools/swagg…

简介:在java代码里面增加注解生成接口文档

RestController
@RequestMapping("api/v1/user")
@Api(tags = "用户模块",value = "用户UserController")
public class UserController {
​
    @Autowired
    private BannerService bannerService;
​
    @ApiOperation("分页用户列表")
    @GetMapping("list")
    public JsonData list(){
​
        List<BannerDO> list = bannerService.list();
​
        return JsonData.buildSuccess(list);
    }
}
复制代码

优点

  • 支持SpringMVC、SpringBoot、SpringCloud等主流java框架
  • 对java代码友好
  • 界面简介
  • 国内比较活跃,主要是Spring社区带动
  • 功能比较多

缺点

对跨语言支持不好(可以喝knife4j整合解决这个问题)

代码需要引入相关依赖包和配置

文档相对缺少

SpringFox3.X和Swagger3.X介绍

Swagger介绍

基于OpenAPI规范构建的开源接口文档自动生成工具,可以让开发人员快速设计、构建、记录以及使用RestAPI

版本说明

目前的版本有swagger2.0和3.0

Swagger2于17年停止维护,现在最新的版本为17年发布的swagger3(OpenApi3)

Swagger主要包含以下三个部分

  • SwaggerEditor:基于浏览器的编辑器,我们可以使用它来编写我们OpenAPI规范
  • SwaggerUi:它会将我们编写的OpenAPI规范呈现为交互式的API文档
  • SwaggerCodegen:它可以通过OpenAPI(以前称为Swagger)规范定义的任何API生成服务器存根和客户端SDK来简化构建过程

SpringFox介绍

(是spring社区维护的一个非官方项目)

是一个开源的API Doc的框架,Marty Pitt编写了一个基于Spring组件的Swagger-SpringMvc,用于将Swagger集成到Springmvc中来,它的前身是Swagger-Springmvc,可以将我们的Controller中的方法以文档的形式展现

地址:github.com/springfox/s…

版本说明

  • SpringFox3.0.0(减少了Swagger2的一些配置)
  • Spring5 Webflux支持,依赖少
  • 支持OpenApi 3.0.3
  • 有SpringBoot的整合的starter,使用更便捷

SpringBoot2.X整合Swagger3.0

Step1:pom添加依赖

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
</dependency>
复制代码

Step2:配置文件

#spring.application.name=shop-managerp接口,增加中文会乱码,可以修改文件编码,或者使用yml格式
spring.application.name=shop-manager
# ===== 自定义swagger配置 ===== #
swagger.enable=true
swagger.application-name= ${spring.application.name}
#接口文档版本
swagger.application-version=1.0
#swagger.application-description=该接口文档的描述
swagger.application-description=1024shop api info 
复制代码

Step3:配置类

@Component//Spring扫描
@EnableOpenApi//开启OpenApi规范
@ConfigurationProperties("swagger")//配置前缀
@Data
public class SwaggerConfiguration {
    /**
     * 是否开启swagger,生产环境一般关闭,所以这里定义一个变量
     */
    private Boolean enable;
​
    /**
     * 项目应用名
     */
    private String applicationName;
​
    /**
     * 项目版本信息
     */
    private String applicationVersion;
​
    /**
     * 项目描述信息
     */
    private String applicationDescription;
​
​
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")
​
        // 定义是否开启swagger,false为关闭,可以通过变量控制,线上关闭
                .enable(enable)
​
        //配置api文档元信息
                .apiInfo(apiInfo())
​
        // 选择哪些接口作为swagger的doc发布
                .select()
​
        //apis() 控制哪些接口暴露给swagger,
        // RequestHandlerSelectors.any() 所有都暴露
        // RequestHandlerSelectors.basePackage("com.keep.*")  指定包位置
        // withMethodAnnotation(ApiOperation.class)标记有这个注解 ApiOperation
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
​
                .paths(PathSelectors.any())
​
                .build();
    }
​
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                .contact(new Contact("作者", "网站", "邮箱"))
                .version(applicationVersion)
                .build();
    }
}
复制代码

🦂注意

Http://localhost:端口/swagger-ui/index.html

如果启动后访问不成功,查看是否有拦截器拦截了相关资源配置,配置不拦截即可

Swagger3.X常用注解和配置

@Api

模块配置,用在Controller类上,描述Api接口

    @Api(tags = "用户模块",value = "用户UserController")
    public class UserController {
    }
复制代码

@ApiOperation

接口配置,用在方法上,描述接口方法

    @ApiOperation("分页用户列表")
    @GetMapping("list")
    public JsonData list(){
        return JsonData.buildSuccess();
    }
复制代码

@ApiParam

方法参数配置,用在入参中或注解中

    @ApiOperation("用户登录")
    @GetMapping("login")
    public JsonData login(
            @ApiParam(name = "phone", value = "手机号",example = "13888888888")
            @RequestParam("phone") String phone,
​
            @ApiParam(name = "pwd", value = "密码",example = "123456")
            @RequestParam("pwd")String pwd){
​
        return JsonData.buildSuccess();
    }
复制代码

    @RequestMapping(value = "/test",method = RequestMethod.GET)
    @ApiOperation(value = "文档描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name1",value = "名称1",defaultValue = "空串",required = true,paramType = "query"),
            @ApiImplicitParam(name = "name2",value = "名称2",defaultValue = "空串",required = true,paramType = "query")
    })
    public String test(String name1,String name2) {
        //language=JSON
        String aa = "{n  "name": "张三",n  "age": 21n}";
        return name1+name2;
    }
​
复制代码

@Apilgnore

忽略此接口不生成文档

    @ApiIgnore
    @ApiOperation("删除用户")
    @DeleteMapping("/delete/{id}")
    public JsonData  deleteById(@PathVariable int id) {
        return JsonData.buildSuccess();
    } 
复制代码

Swagger3.X对象注解ApiModel讲解

@ApiModel

用于类 表示对类进行说明,用于参数用实体类接收,value-表示对象名,description-描述

这种一般用在post创建的时候,使用对象提交这样的场景

@ApiModelProperty

用于方法,字段;标识对model属性的说明或者数据操作更改

Value:字段说明

Name:重写属性名字

DateType:重写属性类型

Required:是否必填

Example:举例说明

Hidden:隐藏

🌰

@Api(tags = "用户模块",value = "用户Controller")
@RestController
@RequestMapping("api/v1/user")
@Slf4j
public class UserController {
​
    @ApiOperation("新增用户")
    @RequestMapping(value = "/saveUser",method = RequestMethod.POST)
    //public JsonData saveUser(@RequestBody UserParam userParam){ 用于发送json请求
    public JsonData saveUser(UserParam userParam){//用于表单请求
        log.info("UserController.saveUser 新增用户 Param:{}",userParam);
        return JsonData.buildError("新增成功");
    }
}
复制代码
@ApiModel(value = "新增用户请求模型")
@Data
public class UserParam {
​
    @ApiModelProperty(value = "主键")
    private int id;
​
    @ApiModelProperty(value = "邮箱",required = true,example = "736317048@qq.com")
    private String email;
​
    @ApiModelProperty(value = "手机号",required = false)
    private String phone;
​
    @ApiModelProperty(value = "用户名称")
    private String name;
}
复制代码

Swagger3.X响应结果ApiResponse

@ApiResponse

描述接口响应

🌰 注意要导Swagger3的包才能有以下属性

    @ApiOperation(value = "轮播图信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "主键id",defaultValue = "空串",required = true,paramType = "query")
    })
    @ApiResponses({
            @ApiResponse(responseCode = "401",description = "请进行身份验证"),
            @ApiResponse(responseCode = "403",description = "拒绝执行"),
            @ApiResponse(responseCode = "404",description = "资源未找到"),
            @ApiResponse(responseCode = "500",description = "系统异常")
    })
    @RequestMapping(value = "/getBannerById",method = RequestMethod.GET)
    public JsonData getBannerById(@RequestParam Long id){
        try {
            BannerDO bannerDO = bannerService.getBannerById(id);
            return JsonData.buildSuccess(bannerDO);
        }catch (Exception e){
            log.error("BannerController.getBannerById  Exception -> error:{}, param:{}",e,id);
        }
        return JsonData.buildError("查询失败",-1);
    }
复制代码

感觉不错的大佬点个赞呗 演示不易

原创文章,作者:睿达君,如若转载,请注明出处:https://zrrd.net.cn/2328.html

发表评论

登录后才能评论
咨询电话
联系电话:0451-81320577

地址:哈尔滨市松北区中小企业总部基地13F

微信咨询
微信咨询
QQ咨询
分享本页
返回顶部