这是一个创建于 220 天前的主题，其中的信息可能已经有所发展或是发生改变。
按理来说 openAPI 的 schema 应该先设计好, 然后生成 swagger ui, 但是现在 Java 用注解生成 openAPI 是不是本末倒置?
19 条回复 • 2024-06-06 11:02:43 +08:00
 |
1
julyclyde 220 天前  1
1 这事其实和 java 没啥关系
2 初版 API 规范用注解来生成其实也没什么不合适的，只要别改来改去就可以 |
 |
2
lolizeppelin 220 天前 2
这本质是一个工程问题
方式 1： 设计人员设计好结构, 接口, 编写文档,由设计指导代码编写 方式 2： 开发人员编写代码后,同步文档 1 和 2 的本质区别,在于结构、接口、文档是开发人员负责还是专门的部门、人员负责 如果根本不存在一个专门部门或者人员负责文档和结构设计,自然倾向于自动生成文档和结构 注解生成只是自动生成的方式 |
 |
3
bxb100 OP @julyclyde @lolizeppelin 我不是说这个行为对或者错, 而是在于写 spec 的过程是一个思考的过程, 比如说如何分类, 如何复用, 如何验证. 直接用注解生成一个是有侵入性, 第二个 UI 也不美观, 第三个是写接口的时候突出一个随意, 没有文档, 没有思考过程.
有没有专门 doc developer 来做和这个事情值不值得做是两个问题, 我主要是想问大家是怎么看待这个事情, 或者有啥其它的真知灼见 |
 |
6
hoko1814 220 天前
我理解成那个 swagger 了，溜……
|
|
7
lolizeppelin 220 天前 1
@bxb100
你说的没错, spec 和接口的设置本身就是要适配需求、甚至要预留未来需求，本身就是需要比一般代码人员更熟悉的人来编写的 但是实际项目中,根本没人、或者根本没时间干这个事, 大部分时间都再怼业务代码、需求还改来改去导致接口与结构都一直在变化 这种情况下还把文档、结构和代码分开，那么反而会成为累赘,还不如写什么代码就生成什么文档和结构 这种反向自动生成行为本身就是为了适应环境的结果,是结果,不是目的 你要知道更差劲的结果是: 设计的文档、结构、接口和代码根本对不上、因为根本没人管 |
 |
8
iyiluo 220 天前 1
开发过程中接口变动很常见，按部就班开发是非常理想化的设想，在现实中几乎不可能
|
|
9
bxb100 OP @lolizeppelin #7 多谢回复
|
 |
10
leegradyllljjjj 220 天前
年轻人还在这儿研究茴字儿的写法，部门领导 pm 只会关心什么时候能上线
|
 |
11
siteshen 220 天前
如果 spec 能方便地增量生成后端代码框架，先定义 spec 也不会造成额外的负担。而实际上，先设计 schama ，后端要做的是按照设计的 schema 重新用代码实现一遍 input, output, validation ，增加无谓的重复工作。
所以我选择倾向于用第二种方式，对增量的 API 开发更友好。 利益相关：后端开发。 |
 |
13
susuper 220 天前
swagger-codegen 可以生成 ts 、java 等前后端代码，前后端都可以写 SPEL ，然后利用工具生成各自接口层，前端实现调用方法，后端实现继承接口。
|
 |
14
chuck1in 220 天前
先做 spec 再实现这种方式也不是不行，不过有个问题，就是他对整体效率和工程质量的把控上是否有更大的提升。
有的话，我觉得就可以搞，如果没有的话，就不一定要搞。 大家怎么看呢。 |
 |
17
houzhiqiang 219 天前
FastAPI 先写接口定义(方法签名)然后就可以生成 openapi 了，部署到测试环境，接下来补充实现
@router.get("/users", name="get user") def get_user(id: int) -> User: # TODO: do something ... return User(name="u", ) |
 |
19
smartdoc647 196 天前
线设计 API 文档和工具并不冲突，比如我最近的开发方式：
1 、分析需求文档 2 、用自己开发的 SpringBoot 脚手架创建一个空的 SpringBoot 项目用于建模 API 接口 3 、思考需求，在 2 步骤创建的 API 建模项目中定义空结构体和空 Controller 接口 4 、用 smart-doc 扫描定义的空接口生成 API 文档 5 、用生成的 API 文档和前端和产品人员完成定稿和微调。 6 、启动正式项目开发，完全复制一些前面编写空接口的结构体。 |
Select Language