
Python与Ollama的开发案例
在微服务架构与 API 驱动时代,OpenAPI 规范已成为业界设计与管理 RESTful API 的事实标准。通过 OpenAPI,你可以在API 设计、API 文档、自动生成客户端 SDK、服务端 Stub、Mock 服务、持续集成等环节实现全流程的自动化与契约优先,大幅提升团队协作效率、降低重复工作量,确保前后端、内外部合作方对 API 能够“一次定义,多处复用”。
基于该契约,可自动生成:
openapi: 3.0.0
info:
title: 示例 API
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths: {}
components: {}
security: []
title
、version
、description
,利于搜索结果中精准命中“OpenAPI 规范定义”关键词。https://api.dev.example.com
、https://api.prod.example.com
,提升文档可读性。parameters
(路径、查询、头部)与 requestBody
、responses
,便于通过 API 文档生成工具(如 Swagger UI)一键查看。openapi: "3.0.0"
info:
title: 艺术家管理 API
description: 完整示例,演示 OpenAPI 定义、生成与集成流程
version: "1.0.0"
servers:
- url: https://api.example.com/v1
components:
schemas:
Artist:
type: object
required:
- username
- name
properties:
username:
type: string
description: 艺术家用户名
name:
type: string
description: 艺术家全名
genre:
type: string
description: 艺术家流派
paths:
/artists:
get:
summary: 获取艺术家列表
parameters:
- name: limit
in: query
schema:
type: integer
description: 每页数量
- name: offset
in: query
schema:
type: integer
description: 跳过数量
responses:
"200":
description: 成功返回艺术家列表
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Artist'
post:
summary: 创建新艺术家
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Artist'
responses:
"201":
description: 创建成功
以上 YAML 演示了 OpenAPI 规范定义 的核心要素:清晰的 Schema 复用、完善的 路径参数 与 响应模型。
特性 | Swagger Codegen | OpenAPI Generator |
---|---|---|
支持语言 | 30+ | 50+ |
社区活跃度 | 中等 | 高 |
模板定制与扩展 | 有限 | 强 |
与最新 OpenAPI 3.1 支持 | 较弱 | 完全兼容 |
推荐使用 OpenAPI Generator,它对 TypeScript、Python、Java、Go 等主流语言提供了更完善的支持。
# 生成 Python-Flask Server Stub
openapi-generator-cli generate \
-i openapi.yaml \
-g python-flask \
-o ./server
# 生成 TypeScript Fetch 客户端
openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-fetch \
-o ./client-ts
./server/controllers
、./server/models
下即得可运行的 服务端骨架./client-ts
下得到封装好的 ApiClient.ts,可直接在前端项目中引入调用openapi.yaml
导入 Apidog,一键生成在线文档、Mock Server在项目中仅需引入对应依赖:
npm install swagger-ui-dist
# 或者 pip install swagger-ui-bundle
并在后端静态挂载 /docs
路由即可。
在 Spring Boot 项目中添加依赖:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.6.0</version>
</dependency>
启动项目后访问 http://localhost:8080/swagger-ui.html
即可查看自动生成的 Swagger UI 文档。
openapi-validator
校验 OpenAPI 文件合法性nullable
行为变化,更好地与 JSON Schema 规范对齐$ref
引用外部文件),提升可维护性最佳实践小贴士:
通过以上“定义(Define)→生成(Generate)→集成(Integrate)”三大步骤,你将真正 全面掌握 OpenAPI 规范,构建出高质量、可维护、易扩展的 API 生态,并在搜索引擎中稳居“OpenAPI 教程”、“OpenAPI Generator 教程”、“OpenAPI 集成指南”等关键词的前列。
原文引自YouTube视频:https://www.youtube.com/watch?v=bseJ45zejZU