Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

OpenAPI vocabulary or dialect for code generation

Đang mở
  • Có gì không ổn?
#2,542 12 bình luận 7 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
openapi
Lĩnh vực
api

Hướng nghiên cứu

Bắt đầu với issue #2542 và xem xét các hạn chế về việc tạo mã được liệt kê cùng những lý do của chúng. Xác định xem dự án muốn có một từ vựng hoặc phương ngữ OpenAPI dùng chung hay không, sau đó xác định một bộ quy tắc đã được thống nhất và cách mã hóa bộ quy tắc đó. Được xem là hoàn thành khi phạm vi và cách biểu diễn đã được giải quyết, thay vì vẫn chỉ là một đề xuất.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Markdown
Star
31.2k
Fork
9.2k
Merge trung bình
2 ngày 9 giờ
Pull request đã merge (30 ngày)
17

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của OAI/OpenAPI-Specification

Tất cả issue của OAI/OpenAPI-Specification

Issue tương tự

Thêm issue về Backend & API Design

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.