Swagger学习(一)之Swagger2入门

我是一个小仓鼠01

已于 2022-07-23 18:39:28 修改

阅读量1.2k

点赞数

分类专栏： Api对接文档文章标签：学习 java 开发语言

于 2022-07-22 17:33:52 首次发布

本文链接：https://blog.csdn.net/weixin_53998054/article/details/125926158

版权

Api对接文档专栏收录该内容

4 篇文章 1 订阅

订阅专栏

SpringBoot集成Swagger

Swagger简介

前言

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际请求不一致。

很多人员会抱怨写的接口文档不规范，不及时更新。当时当自己写的时候确实很烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。

如果接口文档可以实时动态生成就不会出现上面的问题。

Swagger可以完美的解决上面的问题

OpenApi是什么

OpenAPI规范（也称为Swagger规范）是REST API的API描述格式。OpenAPI文件可以描述整个API：

OpenApi文件允许描述整个API包括

每个访问地址的类型。POST或者GET

每个操作的参数。包括输入输出参数

认证方法

连接信息，声明，使用团队和其他信息。

API规范（OpenAPI 3.0规范）可以用YAML或JSON编写。这样更利于我们和机器进行阅读。

OpenAPI规范为REST API定义一个语言无关的标准接口，允许和计算机发现和理解服务的功能，而无需要访问源代码，文档或者通过网络流量。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。

然后，文档生成可以使用OpenApi定义来显示Api，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例。

源码和说明参数

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasDocument

Swagger简介

Swagger是一套围绕OpenApi规范构建的开源公具,可以帮助设计，构建，记录和使用REST API。

Swagger工具包括的组件:

Swagger Editor:基于浏览器编辑器，可以在里面编写OpenApi规范。类似Markdown具有实时预览描述文件的功能。

SwaggerUI:将OpenApi规范呈现为交互式Api文档。可用可视化UI展示描述文档。

SwggerCodegen:将OpenAPI规范生成为服务器存根和客户端库。通过SwaggerCodegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种语言的客户端和服务端代码。

Swagger Inspector:和Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。

SwaggerHub:集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

所有Swagger，就是把相关的信息保存在它定义的描述文件里面(yml或者json格式)，再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

Springfox

使用Swagger时如果碰见版本更新或者迭代时，只需要更改Swagger的描述文件即可。

但是再频繁的更新项目版本时很多开发人员认为即使描述文件(yml和json)也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成的接口文档页失去了意义。

Marty Pitt编写了一个基于Spring组件Swagger-Springmvc。Spring-fox就是根据这个组件发展而来的全新项目。

Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。

Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确实方便很多。

所以再实际开发中我们更多的使用Spring-fox。

附:官网地址

http://springfox.github.io/springfox/docs/current/

附:官网地址

https://github.com/springfox/springfox

swagger常用注解

Swagger2常用注解

1.Api

@Api是类上注解。控制整个类生成接口信息的内容。

tags:类的名称。可以有多个值，多个值表示多个副本。

description:描述，已经过时

value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@RestController
@RequestMapping("people")
@Api(tags={"mydemo"},description"描述")
public class DemoController{

@ApiOperation

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

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

@ApiModel、@ApiModelProperty

@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

@ApiIgnore

@ApiIgnore //ApiIgnore-忽略,当前注解描述的方法或者类型,不生成api帮助文档

@ApiResponses、 @ApiResponse

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

@Api(tags = {"Hello控制类","userController"},description = "测试Api描述信息")
@RestController
@RequestMapping(value = "hello")
public class UserController {

   

    @PostMapping(value = "/Hello2")
    @ApiOperation(value = "Post方法，执行查询操作",notes = "Swagger学习-处理POST请求的方法")
    public String hello2(@ApiParam(name = "用户名(username)",value = "新增用户时候提供的用户名",required = true) String username){
        return "hello"+username;
    }


//ApiIgnore - 忽略，当前注解描述的方法或者类型，不生成Api帮助文档
  @ApiIgnore
    @GetMapping(value = "/getUser")
    public String user(String username){
        return "username"+username;
    }

    @GetMapping(value = "/getUser2")
//    @ApiImplicitParam(name = "username",value = "用户名",required = false,paramType = "字符串",dataType = "明值对")
    @ApiImplicitParams(
            value ={
            @ApiImplicitParam(name = "username",value = "用户名",required = false,paramType = "字符串",dataType = "明值对"),
            @ApiImplicitParam(name = "password",value = "用户名",required = true,paramType = "字符串",dataType = "明值对")
            }
    )
    public String getUser2(String username,String password){
        return "username"+username+password;
    }

}

实体类配置

@ApiModel、@ApiModelProperty

@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

@Apilgnore

@Apilgnore


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

@ApiModel(value="用户实体类",description="描述实体使用的文字")
public class User {
    @ApiModelProperty(value="用户名",name="主键（id）",required=false,example="1",hidden=false)
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

自定义注解设置不需要生成接口文档的方法

自定义注解

注解名随意

包名是anno


import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/*
* @Target-描述当前的注解可以定义在什么资源上。
* 属性value
* -定义具体的资源包括:
* -ElementType.METHOD 可以定义在方法上
* -Element.Type 可以定义在类型上
* -Element.FLELD 可以定义在属性上
* -Element.PARAMETER可以定义在方法的参数上
* @Retention -当前注解在什么时候有效
* 属性value
* -定义具体的生效标记
* -RetentionPolicy.RUNTIME-允许时有效
* -RetentionPolicy.SOURCE -源码中有效
* -RetentionPolicy.RUNTIME -字节码有效
* */
@Target(value = {ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation4Swagger {
    //自定义注解中的属性。相当于@MyAnnotation4Swagger
    String value() default "";
}

使用

    @MyAnnotation4Swagger
    @RequestMapping(value = "/user")
    public String username(String username){
        return "username"+username;
    }

实体类

@Apimodel

@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

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

import java.io.Serializable;
/*
* ApiModel -描述一个实体类类型。
* 这个实体类如果成为任何一个生成api帮助文档方法的返回值类型的时候，此注解被解析
* */
@ApiModel(value = "用户实体类",description = "用户数据")
public class User implements Serializable {
    @ApiModelProperty(value = "主键",name = "主键(id)",required = false,
            example = "1",hidden = false)
    public String id;
    @ApiModelProperty(value = "用户名",name = "用户名(username)",required = true,example = "张三",hidden = false)
    public String username;
    @ApiModelProperty(value = "密码",name = "密码(password)",required = true,example = "13456",hidden = false)
    public String password;
}