从最简单的 HTTP 接口开始，再接入接口文档和调试页面。这是后续业务接口与合约服务联调的准备。
本文由个人备赛旧笔记整理，整理日期为 2026-11-03。命令、输出和测试记录属于当时的实验环境；本文未重新搭建整套环境验证。
阅读前先确认
文中出现的 Spring Boot CLI 快照地址和依赖版本是当时的记录。Springfox 与 springdoc 是不同方案，不能直接混配；先确认项目的 Spring Boot 主版本。
SpringBootWeb
Spring快速开发
比赛使用的后端主要是 Spring Boot web
构建项目
https://start.spring.io/
我们可以使用 start.spring.io快速构建一个 spring项目
他会自动生成项目源代码和项目管理以及项目脚本
附加组件 Spring Boot CLI
下载地址 https://repo.spring.io/ui/native/snapshot/org/springframework/boot/spring-boot-cli/3.2.0-SNAPSHOT/
手动设置变量即可使用：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| PS C:\Users\33454> spring
usage: spring [--help] [--version]
<command> [<args>]
Available commands are:
init [options] [location]
Initialize a new project using Spring Initializr (start.spring.io)
encodepassword [options] <password to encode>
Encode a password for use with Spring Security
shell
Start a nested shell
Common options:
--debug Verbose mode
Print additional status information for the command you are running
See 'spring help <command>' for more information on a specific command.
|
基本接口
字符串返回 text 接口
1
2
3
4
5
6
7
8
9
10
11
12
13
| package com.myproject.demo.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@RequestMapping("/")
public String home() {
return "Hello World!";
}
}
|
Json接口
我们在观察FoodTraceability 这个项目时可以看到，他的依赖里使用了 FastJSON 这个包
所以我们在写Json接口时，应该在确保可以手动使用原始依赖完成Json响应同时，也使用 FastJSON 完成数据构造和响应
代码示例
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
| package com.myproject.demo.controller;
import com.alibaba.fastjson.JSONObject;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
@RestController
public class JsonData {
@RequestMapping(value = "/json", produces = MediaType.APPLICATION_JSON_VALUE)
public String json() {
return "{\"name\":\"通过手动添加响应头返回json数据\",\"age\":1}";
}
@RequestMapping("/json-fastjson")
public JSONObject jsonFastJson() {
JSONObject json = new JSONObject();
json.put("name", "通过设置返回类型为JSONObject返回json数据");
json.put("age", 2);
json.put("city", "北京");
return json;
}
@RequestMapping("/json-map")
public Map<String, Object> jsonMap() {
Map<String, Object> data = new HashMap<>();
data.put("name", "Map类型会自动设置相应头为 application/json");
data.put("age", 3);
data.put("hobbies", Arrays.asList("唱", "跳", "Rap篮球"));
return data;
}
}
|
分析：
- 比赛的示例代码主要使用手动设置响应头的方式，即设置
produces的值。
- 这是因为比赛示例接口的代码均使用了 String 作为返回类型
- 例：
public String add_trace_by_distrubutor(@RequestBody JSONObject jsonParam) {
比赛后端的运行逻辑：
Vue.js + (Thymeleaf)+ Spring Boot Web <—> WeBase-Front
前端使用了Thymeleaf 作为模板引擎，然后引入了vue.js 组件
Spring-swagger
swagger
一个老牌的集成在后端中的API测试工具，现在更推荐使用Spring Open API DOCS 的方式
但是比赛用到了这个，还是学习一下
首先在项目中集成
1
2
| implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.13'
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.13'
|
这里我暂时用了更现代的 gradle
我特意查了一下，更老版的依赖导入方式有
1
2
| implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'
|
然后在接口中我们要引入这个库，并参加相应的注解
由于不兼容，我们先用兼容的Spring Open API DOCS
这个就是 swagger version 3 换名字罢了，连依赖和URL都是写的swagger
先写好注解
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| package com.myproject.demo.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@RequestMapping("/")
@Operation(summary = "返回文本罢了", description = "没啥意思")
@ApiResponse(responseCode = "200", description = "返回成功")
@ApiResponse(responseCode = "404", description = "返回失败")
public String home() {
return "Hello World!";
}
}
|
注意这个文件application.properties
需要补充内容
1
2
3
4
| spring.application.name=demo
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.enabled=true
|
这样我们就可以在项目运行的时候通过浏览器访问了
http://127.0.0.1:8080/swagger-ui
成功访问
复现时的自查
- 记录自己实际使用的版本、配置和缺失依赖。
- 对照本篇关键步骤，保存命令或调用结果，并解释结果代表什么。
- 对失败或与原记录不一致的情况保留错误信息，不把历史输出当成自己的验证结果。
返回系列导读 · 上一篇 · 下一篇
