Swagger技术 - 技术栈

1.什么是swagger

Swagger 是⼀款 RESTFUL 接⼝的⽂档在线⾃动⽣成+功能测试功能软件。 Swagger 是⼀个规范和完整的框架，⽤于⽣成、描述、调⽤和可视化 RESTful ⻛格的 Web 服务。⽬标是使客户端和⽂件系统作为服务器以同样的速度来更新⽂件的⽅法，参数和模型紧密集成到服务器。这个解释简单点来讲就是说， swagger 是⼀款可以根据 RESTful ⻛格⽣成的⽣成的接⼝开发⽂档，并且⽀持做测试的⼀款中间软件。

1.1为什么使用swagger

为什么使⽤ Swagger 我们从三个⽅⾯去说它：

对于后端开发⼈员

不⽤再⼿写 WiKi 接⼝拼⼤量的参数，避免⼿写错误
对代码侵⼊性低，采⽤全注解的⽅式，开发简单
⽅法参数名修改、增加、减少参数都可以直接⽣效，不⽤⼿动维护
缺点：增加了开发成本，写接⼝还得再写⼀套参数配置

对于前端开发

后端只需要定义好接⼝，会⾃动⽣成⽂档，接⼝功能、参数⼀⽬了然
联调⽅便，如果出问题，直接测试接⼝，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

对于测试

对于某些没有前端界⾯ UI 的功能，可以⽤它来测试接⼝
操作简单，不⽤了解具体代码就可以操作
操作简单，不⽤了解具体代码就可以操作

2.如何实现的

2.1导包

XML 复制代码

    <dependencies>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.6.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

2.2配置application.yml

XML 复制代码

server:
  port: 8010
springdoc:
  swagger-ui:
    path: /swagger-ui.html

2.3写配置类（config.SwaggerConfiger.java）

java 复制代码

package com.jiazhong.mingxing.boot.boot10.config;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;
@OpenAPIDefinition(
        info =@Info(
                title = "我是swagger3",
                description = "这是我的第一个swagger3",
                version = "v1.0.0",
                contact= @Contact(
                        name = "张三",
                        email = "zhangsan@qq.com"
        )
        )
)

2.4写API（controller.FirstController.java）

java 复制代码

package com.jiazhong.mingxing.boot.boot10.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/first")
@Tag(name = "firstController",description = "一个测试接口API")
public class FirstController {

    @GetMapping("/a")
    @Operation(description = "a方法，调用后会获取到一些信息")
    public String a(){
        return "This is FirstController`a method!";
    }
}

启动后在浏览器中输入localhost:8010/swagger-ui.html启动

3.相关注解

基本信息注解
分组注解
请求⽅法注解
响应注解

注解相关规范：https://openapi.xiniushu.com/

3.1基本信息注解

3.2分组注解

⽤于对 API 进⾏分组。可以在控制器类或⽅法级别上使⽤。

3.3请求方法注解

以下注解⽤于描述 API 的请求⽅法：

3.4响应注解

以下注解可以在请求⽅法注解 @Operation 中使⽤，也可以单独使⽤。以下注解⽤于描述 API 的响应结果：

示例：

java 复制代码

package com.jiazhong.mingxing.boot.boot10.controller;

import com.jiazhong.mingxing.boot.boot10.bean.Book;
import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/book")
@Tag(name = "bookController",description = "图书接口,实现了图书的添加、修改、上传图书信息等操作",
        externalDocs = @ExternalDocumentation(description = "参考文档",url = "https://www.baidu.com")
)
public class BookController {
    @PostMapping("/save")
    @Operation(
            description = "图书录入接口，将数据录入到数据库中",
            parameters = {
                    @Parameter(name = "bookName",description = "图书名称",required = true),
                    @Parameter(name = "number",description = "图书的数量，要求数量大于0"),
                    @Parameter(name = "price",description = "图书的价格，单位人民币")
            },
            responses = {
                    @ApiResponse(
                            description = "成功的返回，返回success",responseCode = "200"
                    ),
                    @ApiResponse(
                            description = "失败的返回，返回error",responseCode = "500"
                    )
            }
    )
    public String save(String bookName, int number, HttpServletResponse response){
        int num=(int)(Math.random()*100+1);
        if (num%2==0){
            response.setStatus(200);
            return "success";
        }
        response.setStatus(500);
        return "error";
    }
    @Operation(
            description = "修改API接口",
            parameters = {
                    @Parameter(name = "图书信息")
            }
    )
    @PutMapping("/update")
    public String update(Book book){

        return "success";
    }

}