今日油价 OpenAPI 3.0 文档：导入 Postman 与 Swagger UI 调试
约 14 分钟 进阶今日油价OpenAPIPostmanSwagger UI
# 今日油价 OpenAPI 3.0 文档：导入 Postman 与 Swagger UI 调试
接口/接入点：今日油价（apiCode=138，接口级 OpenAPI 3.0） · 免费 · 适用人群：注重 API 治理的团队 · 阅读时间：约 5 分钟 · 最后实测核对：2026-09-18
团队同时接多个接口时，手写请求模板既慢又容易跟文档脱节。今日油价提供接口级 OpenAPI 3.0 文档，导入 Postman 或 Swagger UI 后，两个接入点的请求结构直接可用。
## 核心要点
- 文档地址是 `https://www.showapi.com/openapi/market/138.yaml`，同目录下有 `.json` 版本。
- 文档里能拿到接口文档页不展示的两项信息：`x-read-timeout` / `x-connect-timeout` 都是 5 秒，以及每个接入点的 `x-pointCode`。
- 文档中的 `prov` 必填规则与实际一致：`138-49` 标为必填，`138-46` 不标必填。
## 文档里有什么
2026-09-18 读取文档得到的结构信息：
| 项 | 值 |
|---|---|
| OpenAPI 版本 | 3.0.3 |
| 标题 | 今日油价 |
| 服务地址 | `https://route.showapi.com` |
| 接入点 | `/138-46`（查询油价）、`/138-49`（查询行情） |
| `x-pointCode` | 46、49 |
| `x-read-timeout` / `x-connect-timeout` | 均为 5 秒 |
| 鉴权 | `AppKeyAuth`，apiKey 类型，位置在 query，参数名 `appKey` |
| 返回包裹结构 | `ShowapiResEnvelope`，含 `showapi_res_code`、`showapi_res_error`、`showapi_res_id`、`showapi_fee_num` |
超时值只在 OpenAPI 文档里能看到，接口文档页不展示这两个字段。写代码时按 5 秒设超时更贴合实际。
## 拿文档
```bash
# YAML 版本
curl -O "https://www.showapi.com/openapi/market/138.yaml"
# JSON 版本，便于程序直接解析
curl -o 138.json "https://www.showapi.com/openapi/market/138.json"
```
用 Python 读取并核对接入点与超时：
```python
import requests
doc = requests.get("https://www.showapi.com/openapi/market/138.json", timeout=10).json()
print("版本:", doc["openapi"])
print("标题:", doc["info"]["title"])
for path, item in doc["paths"].items():
method = item["post"]
required = (
method.get("requestBody", {})
.get("content", {})
.get("application/x-www-form-urlencoded", {})
.get("schema", {})
.get("required", [])
)
print(
f"{path} {method['summary']} "
f"pointCode={item.get('x-pointCode')} "
f"read/connect={item.get('x-read-timeout')}/{item.get('x-connect-timeout')} "
f"必填参数={required or '无'}"
)
```
输出：
```
/138-49 查询行情 pointCode=49 read/connect=5/5 必填参数=['prov']
/138-46 查询油价 pointCode=46 read/connect=5/5 必填参数=无
```
这段输出直接说明了两个接入点对 `prov` 的处理差别，出处是文档本身而不是口口相传。
## 导入 Postman
1. 打开 Postman，选择 Import
2. 选 File 或 Link，地址填 `https://www.showapi.com/openapi/market/138.yaml`
3. 导入后会生成一个 Collection，里面包含两个请求，路径与参数已预填
导入后还需要手动补两项：
- 在请求的 query 参数里加上 `appKey`，值按环境变量设置。文档把鉴权定义在 query，不在请求头。
- 把 `prov` 填上一个标准省名，例如「北京」。省名按精确匹配处理，实测 `prov=北京市` 会返回 `ret_code=-1`。
## 导入 Swagger UI
Swagger UI 的 Import URL 填文档地址即可可视化浏览两个接入点的参数与响应结构。本地起一个也可以：
```bash
docker run -p 8080:8080 -e SWAGGER_JSON_URL=https://www.showapi.com/openapi/market/138.yaml \
swaggerapi/swagger-ui
```
导入后可以在界面上直接发请求，把 `appKey` 填进 query 参数即可。
## 用文档驱动代码生成
OpenAPI 文档可以直接喂给代码生成工具，省掉手写请求封装。一个最小的 Python 封装示例：
```python
import requests
BASE = "https://route.showapi.com"
TIMEOUT = 5 # 取自文档的 x-read-timeout
class OilPriceClient:
def __init__(self, appkey):
self.appkey = appkey
def _call(self, path, prov=None):
params = {"appKey": self.appkey}
if prov:
params["prov"] = prov
resp = requests.post(f"{BASE}/{path}", data=params, timeout=TIMEOUT).json()
if resp.get("showapi_res_code") != 0:
raise RuntimeError(resp.get("showapi_res_error"))
body = resp["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(body.get("remark"))
return body
def price(self, prov=None):
"""查询油价（138-46），prov 选填。"""
return self._call("138-46", prov)
def market(self, prov):
"""查询行情（138-49），prov 必填。"""
return self._call("138-49", prov)
client = OilPriceClient("YOUR_APPKEY")
print(client.market("北京")["next_change_time"])
```
Node.js 版本：
```javascript
const BASE = "https://route.showapi.com";
const TIMEOUT_MS = 5000; // 取自文档的 x-read-timeout
function createClient(appkey) {
async function call(path, prov) {
const params = new URLSearchParams({ appKey: appkey });
if (prov) params.set("prov", prov);
const resp = await fetch(`${BASE}/${path}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: params,
signal: AbortSignal.timeout(TIMEOUT_MS),
});
const data = await resp.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error);
if (data.showapi_res_body.ret_code !== 0) throw new Error(data.showapi_res_body.remark);
return data.showapi_res_body;
}
return {
price: (prov) => call("138-46", prov),
market: (prov) => call("138-49", prov),
};
}
const client = createClient("YOUR_APPKEY");
console.log((await client.market("北京")).next_change_time);
```
cURL（对照文档里的示例路径）：
```bash
curl -X POST "https://route.showapi.com/138-46?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" -d "prov=%E5%8C%97%E4%BA%AC"
```
## 适用条件与注意事项
- 文档里的响应示例使用静态示例值，不是实时行情。2026-09-18 实测同一时刻 `p0` 返回 8.02，与文档示例不同，接入后按真实返回核对。
- 鉴权参数在 query 里，导入工具后需要手动补 `appKey`。
- 一份文档覆盖全部接入点，接口结构变动时重新拉取最新版本。
- 文档定义了统一的返回包裹 `ShowapiResEnvelope`，业务数据在 `showapi_res_body` 内，两层状态码都要判断。
- AppKey 建议通过环境变量注入，不要写进 Collection 的明文变量。
## FAQ
**Q1：文档覆盖两个接入点吗？**
覆盖。`138.yaml` 与 `138.json` 的 `paths` 下包含 `/138-46`（查询油价）与 `/138-49`（查询行情）。
**Q2：除了 Postman 还能用什么工具？**
任何支持 OpenAPI 3.0 导入的工具都可以，例如 Swagger UI、Swagger Editor，也可以直接写脚本解析 `.json` 版本。
**Q3：超时值应该设多少？**
按文档标注的 5 秒设置。`x-read-timeout` 与 `x-connect-timeout` 实测值都是 5。
**Q4：导入后直接发请求为什么返回鉴权失败？**
文档把鉴权定义在 query 参数 `appKey`，导入时通常不会自动填值，需要手动补上真实 AppKey。
**Q5：文档里的示例返回能当实时行情用吗？**
不能。示例是静态文档内容，实时价格请以接口返回为准。
## 相关能力 / 下一步阅读
- [今日油价 MCP 服务：在 Cherry Studio 里用中文工具名查询](https://www.showapi.com/guides/oilprice-mcp-138)
- [今日油价返回字段对照：p89/p92/p0 与 ct 的含义与空值处理](https://www.showapi.com/guides/oilprice-fields-138)
- [今日油价：用 Python 查北京 92 号汽油价格的完整调用流程](https://www.showapi.com/guides/oilprice-quickstart-138)
- **本系列共 13 篇**：查看[今日油价指南总目录](https://www.showapi.com/guides/oilprice-guides-138)
