Azure / Azure/data-api-builder

[Enh]: Complete our OpenAPI implementation

Offen
#2,276 1 Kommentar 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen
2.x cli cri engine enhancement open-api
Vorherrschende Sprache
C#
Sterne
1.5k
Forks
370
Ø Merge
3 T. 17 Std.
Gemergte PRs (30 T.)
8

Beschreibung

### What

Improve DAB’s OpenAPI generation. Enhance with OpenAPI 3.1.

### Enhancements

#### 1. Per role OpenAPI generation

The OpenAPI document must reflect the permissions and visibility for each role.

* `https://localhost:8080/openapi` → current role by context
* `https://localhost:8080/openapi/anonymous` → anonymous role
* `https://localhost:8080/openapi/authenticated` → authenticated role
* `https://localhost:8080/openapi/{custom-role}` → specific custom role

Each variant filters entities, fields, and methods according to that role’s access.

#### 2. Multi data source awareness

Each operation must indicate which configured data source it targets.

```json
"paths": {
"/api/Author": {
"get": {
"summary": "Get all authors",
"x-data-source": "sql1", // from data-source.name
"responses": { }
}
}
}
```

`x-data-source` maps directly to the `data-source.name` defined in configuration.

#### 3. Include and exclude field support

When entity configuration includes `include` or `exclude`, only permitted properties appear in the OpenAPI schema.

```json
"components": {
"schemas": {
"Author": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" } // for example
}
}
}
}
```

#### 4. Request body strict mode

When `request-body-strict` is enabled, the request and response payloads share the same schema.
Keys are optional in update operations but otherwise identical.

#### 5. Permissions driven REST methods

Generated paths must match `permissions.actions`.
Only allowed HTTP verbs appear for each entity.

```json
"paths": {
"/api/Author": {
"get": { "summary": "Read all authors" },
"post": { "summary": "Create a new author" }
} // for example, no delete
}
```

#### 6. Proper type formats

The OpenAPI schema must include `format` for date and time types.

| SQL Server Type | OpenAPI Type | OpenAPI Format | Example |
| ---------------- | ------------ | -------------- | ----------------------------------- |
| `date` | string | date | "2025-10-29" |
| `datetime` | string | date-time | "2025-10-29T13:45:30Z" |
| `datetime2` | string | date-time | "2025-10-29T13:45:30.1234567Z" |
| `smalldatetime` | string | date-time | "2025-10-29T13:45:00Z" |
| `datetimeoffset` | string | date-time | "2025-10-29T13:45:30.1234567-07:00" |
| `time` | string | time | "13:45:30.1234567" |

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne bei den Einstiegspunkten /openapi, /openapi/anonymous, /openapi/authenticated und /openapi/{custom-role} und untersuche anschließend die bestehende OpenAPI-Generierung und die Verarbeitung der Konfiguration. Vergleiche die generierten Dokumente mit den aufgeführten Anforderungen an Rollen, Datenquellen, Felder, strict-body, Berechtigungen sowie Datums-/Zeitformate; als abgeschlossen gilt die Arbeit, wenn jede Anforderung abgedeckt und durch die entsprechenden Tests verifiziert ist, auch wenn im Issue keine Tests genannt werden.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
csharp, openapi, sql
Bereich
api, backend-api-design, databases
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.