OAI / OAI/OpenAPI-Specification

Components fields name too restrictive?

Offen
#1,387 2 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

clarification examples
Vorherrschende Sprache
Markdown
Sterne
31.2k
Forks
9.2k
Ø Merge
6 Std. 37 Min.
Gemergte PRs (30 T.)
27

Beschreibung

Components fields name currently has this regex as restrictions: ^[a-zA-Z0-9\.\-_]+$
This was mainly discussed and agreed on in #634.

I found this restriction a little too restrictive. I'd imagine that for the Schemas part of the component, most people will use class names as field names. Allowing the period (.) is good because that allows you to add namespace to class name Namespace.ClassName.

However, quite a number of languages have generics and APIs can have request body that are of type implementing generics. The current allowed characters make it very difficult to represent class name that is derived from generic type. The most intuitive (I think) way to represent generic class name as string is to use some kind of brackets/parentheses Namespace.GenericClassName(AnotherClassName). Of course, one can bypass this by using the allowed underscore or hyphen instead, but that just looks plain ugly.

Should we allow parentheses and/or brackets?

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne mit dem im Issue gezeigten Regex für Feldnamen von Komponenten und lies die vorherige Diskussion in #634. Ermittle, ob Klammern oder eckige Klammern für generische Typnamen zulässig sein sollten, und aktualisiere anschließend die Spezifikation sowie alle damit verbundenen Hinweise zur Validierung, sobald die Syntaxentscheidung feststeht.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
openapi
Bereich
api, documentation
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.