Swagger generated Java client objecten bevatten niet alles

[Chris_147]

Hey,
voor een programma dat wij gebruiken, krijgen we een OpenAPI beschrijving.
Nu heb ik niet het gevoel dat deze leverancier heel goed weet hoe een API beschreven moet worden. Ik heb reeds enkele foutjes eruit kunnen halen, maar ben zelf ook geen ontwikkelaar.
Het proces is dus:
- leverancier maakt OpenAPI beschrijving
- ik download die als yaml file en plak die in editor.swagger.io
- daar klik ik dan "Generate Client" en krijg ik dus een nette client
Daar kan ik dan mee aan de slag.

In de swagger zie ik volgend product:

JSON:

{
  "data": [
    {
      "id": "1",
      "type": "product",
      "attributes": {
        "businessId": "PRD1",
        "shortDescription": "A short description",
        "longDescription": "A long description"
      },
      "relationships": {
        "testCycle": {
          "data": {
            "id": "1",
            "type": "testCycle"
          }
        },
        "parent": {
          "data": {
            "id": "1",
            "type": "product"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "string",
    "next": "string",
    "first": "string",
    "last": "string"
  }
}

De beschrijving daarvoor is:

YAML:

    get:
      operationId: getProducts
      description: Fetch all the products
      summary: Retrieve all products
      parameters:
        - in: query
          name: 'page[offset]'
          schema:
            type: integer
          description: The offset from where 10 items will be returned
          required: false
      tags:
        - Products
      responses:
        '200':
          description: Returns all the products
          content:
            application/vnd.api+json:
              schema:
                required:
                  - data
                  - links
                allOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items: $ref: '#/components/schemas/Product'
                  - $ref: '#/components/schemas/Links'

Concreet is mijn probleem dat de links sectie wel in mijn object staat, maar de data sectie niet.
Ik denk dat de kans het grootst is dat de OpenAPI beschrijving niet correct is, dan dat de Swagger generator een fout bevat.


Hoe moet best de structuur:
"data" : [ meerdere_product_objecten ],
"links": 1_links_object
beschreven worden?

[kutagh]

De OpenAPI YAML ziet er gewoon correct uit. Ik kan niet met 100% zekerheid zeggen aangezien de $ref items niet beschikbaar is, maar via "allOf" worden meerdere schema's met elkaar gecombineerd die allemaal een deel van een object kunnen beschrijven.

Uit mijn eerdere ervaringen met swagger heb ik al meegemaakt dat hun tooling niet alle features ondersteunt die in de specificatie mogelijk zijn. Zo gebruiken wij dus geen swagger om de specificatie grafisch te weergeven maar redoc, juist omdat bijvoorbeeld nested oneOf niet goed werd ondersteund. Ik neig dus persoonlijk meer naar de schuld bij de swagger client generator leggen dan bij de schema van je leverancier.

[Chris_147]

Bedankt, maar dat Swagger toch niet correct zou zijn, vind ik dan weer minder.
Betekent dus dat de client genereren niet gaat lukken.

Edit: op dit moment heeft men de response niet als een eigen object (schema) beschreven.
Swagger genereert dan nieuwe objecten met namen zoals InlineResponse2002.java.
Zou Swagger beter werken als die response objecten reeds gedefinieerd zouden zijn?
Voordeel is dan ook dat het response een betere naam heeft in de gegenereerde client.

[ Voor 56% gewijzigd door Chris_147 op 27-03-2023 11:40 ]

[RedFox]

Zie je in de visuele representatie van de API op https://editor.swagger.io/ wel de goede response?
Als ik jouw voorbeeld daar even combineer met de demo data klaagt hij namelijk dat de indenting niet goed is.

code:

                          items: $ref: '#/components/schemas/Product'

zou dit moeten zijn:

code:

                          items: 
                            $ref: '#/components/schemas/Product'

[Chris_147]

Ja, dat klopt! Ik had dit verkeerd gekopieerd.