Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

OpenAPI vocabulary or dialect for code generation

Aperta
  • Qualcosa non va?
#2,542 12 commenti 7 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
openapi
Ambito
api

Direzione di ricerca

Inizia dall’issue #2542 e rivedi le restrizioni sulla generazione del codice elencate e le relative motivazioni. Determina se il progetto vuole un vocabolario o un dialetto OpenAPI condiviso, quindi definisci un insieme di regole concordato e come debba essere codificato. Il lavoro è completato quando l’ambito e la rappresentazione sono definiti, invece di rimanere una proposta.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Markdown
Stelle
31.2k
Fork
9.2k
Merge medio
2g 9h
PR unite (30g)
17

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OAI/OpenAPI-Specification

Tutte le issue di OAI/OpenAPI-Specification

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.