关于 swagger 的疑惑

[bxb100]

按理来说 openAPI 的 schema 应该先设计好, 然后生成 swagger ui, 但是现在 Java 用注解生成 openAPI 是不是本末倒置?

[julyclyde]

1 这事其实和 java 没啥关系
2 初版 API 规范用注解来生成其实也没什么不合适的，只要别改来改去就可以

[lolizeppelin]

这本质是一个工程问题
方式 1： 设计人员设计好结构, 接口, 编写文档,由设计指导代码编写
方式 2： 开发人员编写代码后,同步文档

1 和 2 的本质区别,在于结构、接口、文档是开发人员负责还是专门的部门、人员负责

如果根本不存在一个专门部门或者人员负责文档和结构设计,自然倾向于自动生成文档和结构

注解生成只是自动生成的方式

[bxb100]

@julyclyde @lolizeppelin 我不是说这个行为对或者错, 而是在于写 spec 的过程是一个思考的过程, 比如说如何分类, 如何复用, 如何验证. 直接用注解生成一个是有侵入性, 第二个 UI 也不美观, 第三个是写接口的时候突出一个随意, 没有文档, 没有思考过程.

有没有专门 doc developer 来做和这个事情值不值得做是两个问题, 我主要是想问大家是怎么看待这个事情, 或者有啥其它的真知灼见

[julyclyde]

@bxb100 无法实现的理想，不能叫工程理想

[bxb100]

@julyclyde #4 确实, 不过我在重新找回理想的过程中

[hoko1814]

我理解成那个 swagger 了，溜……

[lolizeppelin]

@bxb100
你说的没错, spec 和接口的设置本身就是要适配需求、甚至要预留未来需求，本身就是需要比一般代码人员更熟悉的人来编写的

但是实际项目中,根本没人、或者根本没时间干这个事, 大部分时间都再怼业务代码、需求还改来改去导致接口与结构都一直在变化

这种情况下还把文档、结构和代码分开，那么反而会成为累赘,还不如写什么代码就生成什么文档和结构


这种反向自动生成行为本身就是为了适应环境的结果,是结果,不是目的

你要知道更差劲的结果是: 设计的文档、结构、接口和代码根本对不上、因为根本没人管

[iyiluo]

开发过程中接口变动很常见，按部就班开发是非常理想化的设想，在现实中几乎不可能

[bxb100]

@lolizeppelin #7 多谢回复

[leegradyllljjjj]

年轻人还在这儿研究茴字儿的写法，部门领导 pm 只会关心什么时候能上线

[siteshen]

如果 spec 能方便地增量生成后端代码框架，先定义 spec 也不会造成额外的负担。而实际上，先设计 schama ，后端要做的是按照设计的 schema 重新用代码实现一遍 input, output, validation ，增加无谓的重复工作。

所以我选择倾向于用第二种方式，对增量的 API 开发更友好。

利益相关：后端开发。

[julyclyde]

@siteshen spec 可以生成后段代码框架啊。很容易的
openapi generator

[susuper]

swagger-codegen 可以生成 ts 、java 等前后端代码，前后端都可以写 SPEL ，然后利用工具生成各自接口层，前端实现调用方法，后端实现继承接口。

[chuck1in]

先做 spec 再实现这种方式也不是不行，不过有个问题，就是他对整体效率和工程质量的把控上是否有更大的提升。
有的话，我觉得就可以搞，如果没有的话，就不一定要搞。
大家怎么看呢。

[bxb100]

@chuck1in 类比于 apache 之类的项目都是先写 RFC 然后再开发的流程非常好, 但是我实际去做就挺不好的, 没啥配合度, 感觉就自己一个人玩

[julyclyde]

@bxb100 apache 这个例子恐怕不正确吧

[houzhiqiang]

FastAPI 先写接口定义(方法签名)然后就可以生成 openapi 了，部署到测试环境，接下来补充实现
@router.get("/users", name="get user")
def get_user(id: int) -> User:
# TODO: do something ...
return User(name="u", )

[siteshen]

@julyclyde 主要是对「增量」不友好。

[smartdoc647]

线设计 API 文档和工具并不冲突，比如我最近的开发方式：
1 、分析需求文档
2 、用自己开发的 SpringBoot 脚手架创建一个空的 SpringBoot 项目用于建模 API 接口
3 、思考需求，在 2 步骤创建的 API 建模项目中定义空结构体和空 Controller 接口
4 、用 smart-doc 扫描定义的空接口生成 API 文档
5 、用生成的 API 文档和前端和产品人员完成定稿和微调。
6 、启动正式项目开发，完全复制一些前面编写空接口的结构体。