Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

OpenAPI vocabulary or dialect for code generation

Abierto
  • ¿Algo no está bien?
#2,542 12 comentarios 7 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
openapi
Área
api

Línea de trabajo

Comienza con el issue #2542 y revisa las restricciones de generación de código enumeradas y sus fundamentos. Determina si el proyecto quiere un vocabulario o dialecto OpenAPI compartido y, después, define un conjunto de reglas acordado y cómo debe codificarse. Se considera terminado cuando el alcance y la representación están resueltos, en lugar de quedar como una propuesta.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Markdown
Estrellas
31.3k
Forks
9.2k
Merge medio
2 d 3 h
PR fusionados (30 d)
8

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de OAI/OpenAPI-Specification

Todos los issues de OAI/OpenAPI-Specification

Issues similares

Más issues de Backend & API Design

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.