小白的悟道
0%

springboot-swagger

发表于 更新于 分类于 Valine：

springboot集成Swagger（springdoc-openapi-ui版本）—图文详细

对于快速迭代的软件开发，会导致软件文档中的API不能及时更新，不同项目组之间的代码协同问题出现了较大的挑战，因此本文简单实验springboot集成swagger动态生成文档，可以边开发代码边生成文档，由于springfox版本老旧已经不在维护，本文使用springdoc方式集成。

使用IDEA快速搭建springboot项目

如果已经搭建好了springboot项目可以跳过这一步

点击左上角菜单New，选择Project

image-20220425221200143

使用Spring Initializr方式创建springboot项目，选择jdk为本地安装的1.8版本，点击下一步

image-20220425221253123

输入swaggertest，点击Next

image-20220425221531778

选择Web，选中Spring Web，点击Next

image-20220425221552296

点击Finish

image-20220425221604507

选择New Window

image-20220425221616947

点击Enable Auto Import

image-20220426204327392

选中SwaggertestApplication，右键选中Run ‘SwaggertestApplication’，点击运行

image-20220426204432339

可以看到程序启动成功，至此springboot项目搭建成功

image-20220426204617091

基于springboot项目集成swagger

访问网址

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

点击较新且使用较多的1.6.6版本

image-20220426204917198

复制maven仓库

1
2
3
4
5
6
<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.6</version>
</dependency>

image-20220426204956427

拷贝到项目pom.xml中

image-20220426205150170

加载完后重新启动程序

image-20220426205233093

程序启动成功

image-20220426205303002

访问http://127.0.0.1:8080/swagger-ui/index.html#/

发现可以访问通了

image-20220426205356057

结合实际项目生成api文档

新建一个包

image-20220426205542256

命名为entity

image-20220426205608190

在entity包下，新建Class类

image-20220426205640774

命名为Order

image-20220426205707214

内容为

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package com.example.swaggertest.entity;

public class Order {
    Integer id;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    String name;
}

image-20220426205846710

新建一个包

image-20220426205917675

命名为controller

image-20220426205943670

controller下新建类

image-20220426210016960

命名为TestController

image-20220426210040693

内容为

  • Tag是为整个controller打了一个标志
  • Parameters为各个输入参数，包括Header头、消息体参数
  • ApiResponses为输出参数，包括类型、约束和案例等
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
package com.example.swaggertest.controller;

import com.example.swaggertest.entity.Order;
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.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.HashMap;
import java.util.Map;

@Controller
@Tag(name = "123")
public class TestController {
    @Operation(summary = "查询test")
    @Parameters({
            @Parameter(in = ParameterIn.HEADER, required = true, name = "tenant_id", example = "1", schema = @Schema(implementation = Integer.class)),
            @Parameter(name = "name", schema = @Schema(implementation = String.class))
    })
    @ApiResponses({
            @ApiResponse(responseCode = "200", content = {
                    @Content(schema = @Schema(implementation = Order.class), mediaType = "application/json"
                            , examples = {@ExampleObject(value = "{\n" +
                            "  \"order\": {\n" +
                            "    \"name\": null,\n" +
                            "    \"id\": null\n" +
                            "  }\n" +
                            "}")}
                    )
            })
    })
    @ResponseBody
    @RequestMapping(name = "test", method = {RequestMethod.GET})
    public Map<String, Object> test() {
        Map<String, Object> map = new HashMap<>();
        Order order = new Order();
        map.put("order", order);
        return map;
    }
}

image-20220426210559291

重新启动程序

image-20220426210719243

可以看到启动成功

image-20220426210748893

访问http://127.0.0.1:8080/swagger-ui/index.html#/

可以看到接口文档创建成功，包含输入和输出

image-20220426210845279

image-20220426210856749

点击Try it out

image-20220426211110045

点击执行

image-20220426211124600

可以看到接口执行成功的结果

image-20220426211139235

总结

至此整个springboot集成Swagger的过程已经完成，更多高级功能可以参考官网文档https://springdoc.org/

例如swagger 2 注解with swagger 3 注解的区别如下等等：

  • Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.

    • @Api → @Tag
    • @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
    • @ApiImplicitParam → @Parameter
    • @ApiImplicitParams → @Parameters
    • @ApiModel → @Schema
    • @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
    • @ApiModelProperty → @Schema
    • @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
    • @ApiParam → @Parameter
    • @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")