Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

v3.3: SAFs -> guidance for constants versus discoverability

Ouverte
  • Quelque chose ne va pas ?
#5,570 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
15/100
Type d'issue
Documentation
Clarté
À clarifier
Activité
Active
Domaine
api, documentation

Piste de recherche

The issue names no file or test. Read the linked discussion in PR 5447 and the existing security authentication framework (SAF) material in the OpenAPI Specification repository to see how runtime-discoverable values are handled today. Done means a proposed written guidance text for SAF authors and for users on conflicts between a document and a runtime value, agreed with maintainers. This is design work, so a newcomer should wait for a decision before starting.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

This is a follow up to this comment https://github.com/OAI/OpenAPI-Specification/pull/5447#discussion_r4221692962 which was left during the TDC call.

Some values, especially in the context of formalized security protocols, could be discovered at runtime through the protocol, and/or specified in the OAD as a constant from the SAF data structure.

An example of that is the GNAP as_url that can be discovered in the www-authenticate header in the 401 response, or specified in the OAD (based on the current proposal at time of writing).

After we spin the wheel on a couple of times on new SAFs (as @handrews has rightfully pointed out that we'll get better answers to those questions through a bit more experience on that new design approach), we should probably provide additional generic guidance that applies to all SAFs:

  • outside of the OAS specification, for the people writing SAFs, when should a "field" that already can be discovered at runtime be available in the data structure as well?
  • in the OAS specification, for users of the specification/SAFs: what to do when a value in the document contradicts a value discovered at runtime?

I hope this issue captures the 2 discussions on the topic accurately. And that it's articulate enough that when we revisit the issue in a couple of months we know what this is about :)

Langage dominant
Markdown
Étoiles
31.3k
Forks
9.2k
Merge moyen
2 j 3 h
PR mergées (30 j)
8

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de OAI/OpenAPI-Specification

Toutes les issues de OAI/OpenAPI-Specification

Issues similaires

Plus d'issues Backend & API Design

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.