Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

OpenAPI vocabulary or dialect for code generation

未关闭
  • 哪里不对？
#2,542 12 条评论 7 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
25/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
停滞
技术栈
openapi
领域
api

调研方向

从 issue #2542 开始，审查其中列出的代码生成限制及其理由。确定项目是否需要共享的 OpenAPI 词汇或方言，然后定义一套达成共识的规则，以及应如何对其进行编码。完成意味着范围和表示方式已经得到解决，而不是仍停留在提案阶段。

由索引模型根据 Issue 内容生成。

描述

schema-object

Code generation tools often have special requirements or restrictions on the structure of an OpenAPI definition (document?) that improve the generated code. Here are some examples of restrictions from the IBM OpenAPI SDK generator:

  • Parameters must be unique by name only, irrespective of "in".

    Rationale: Operation parameters are often rendered as the parameters on a function or method in the target language of the code generator. Since most languages require parameters to have unique names, the code generator would need to incorporate the in of a parameter into its name to prevent name collisions. This is undesirable, since it exposes the mechanics of the API without adding any value.

  • There should be at most one success response with a response body. A 204 and other 2XX is okay, but no other combination of two or more 2XX responses.

    Rationale: In statically-typed languages like Java, the return value of a method must have a single static type. This makes it difficult to represent an operation with two different response schemas as a single method returning a single response type.

  • Property names and parameter names must be "case-insensitive" unique

    Rationale: Code generators often reformat the names of parameters, properties, and schemas to use idomatic case formatting for the target language: lower_snake_case for Python, lowerCamelCase for Java, etc. But this reformatting could introduce naming conflicts if two parameters, e.g. "foo_bar" and "fooBar" are not "case-insensitive" unique.

  • Arrays must contain items of a single type

    Rationale: Many languages require an array to contain only values of a single type.

  • Schema type must specify a single type -- no type arrays

    Rationale: Some widely-used statically-typed languages, e.g. Java and Go) have no provision for "union" types, making it impossible to define a type: [ integer, string ] typed property or parameter.

  • Don't use "nullable"

    Rationale: it's deprecated, and is just an alternate way of expressing type arrays

  • Don't use JSON schema "not"

    Rationale There's no obvious way to represent this in many widely used programming languages.

  • No "if-then-else" in JSON schema

    Rationale There's no obvious way to represent this in many widely used programming languages.

  • The API document should be "self contained" (no external "$refs")

    Rationale: External refs can easily create multiple namespaces for schemas, parameters, security schemes, etc. These are unnecessary complications for code generators.

  • All "$refs" must be to elements in the "components" section of the document

    Rationale: "$ref" targets outside of "components" are unnecessary complications for code generators.

It would be nice to have a common set of rules like this that could be codified into a "Code generation" vocabulary or dialect for OpenAPI.

主要语言
Markdown
星标
31.2k
派生
9.2k
平均合并
2 天 9 小时
30 天内合并 PR
17

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

OAI/OpenAPI-Specification 的其他 Issue

查看 OAI/OpenAPI-Specification 的全部 Issue

相似的 Issue

更多 Backend & API Design Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。