Swagger.yaml częściowo niezgodny ze specyfikacją OpenAPI

[gitrid]

Występuje problem:

• [ ] z zasobem REST API / with a REST API resource
• [ ] ze środowiskiem produkcyjnym / with the production environment
• [ ] ze środowiskiem testowym / with the test environment
• [ ] z logowaniem lub autoryzacją / with login or authorization
• [X] na portalu https://developer.allegro.pl/ / at https://developer.allegro.pl/en/
• [ ] inny / other

Dla 20 responses w swaggerze (https://developer.allegro.pl/swagger.yaml) odpowiedzi nieprawidłowo są podane jako int (np. 200), zamiast str zgodnie ze specyfikacją ('200'). Dla zdecydowanej większości odpowiedzi swagger ma prawidłowe formatowanie, błąd występuje tylko w module /charity, /sale/allegro-prices-account-consent, /sale/allegro-prices-account-eligibility i /sale/allegro-prices-offer-consents.

Lista błędów:

20 validation errors for OpenAPI
paths./charity/fundraising-campaigns.get.responses.200.[key]
  Input should be a valid string [type=string_type, input_value=200, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./charity/fundraising-campaigns.get.responses.400.[key]
  Input should be a valid string [type=string_type, input_value=400, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./charity/fundraising-campaigns.get.responses.401.[key]
  Input should be a valid string [type=string_type, input_value=401, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./charity/fundraising-campaigns.get.responses.403.[key]
  Input should be a valid string [type=string_type, input_value=403, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.get.responses.200.[key]
  Input should be a valid string [type=string_type, input_value=200, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.get.responses.401.[key]
  Input should be a valid string [type=string_type, input_value=401, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.get.responses.403.[key]
  Input should be a valid string [type=string_type, input_value=403, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.get.responses.404.[key]
  Input should be a valid string [type=string_type, input_value=404, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.put.responses.200.[key]
  Input should be a valid string [type=string_type, input_value=200, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.put.responses.400.[key]
  Input should be a valid string [type=string_type, input_value=400, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.put.responses.401.[key]
  Input should be a valid string [type=string_type, input_value=401, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.put.responses.403.[key]
  Input should be a valid string [type=string_type, input_value=403, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.put.responses.404.[key]
  Input should be a valid string [type=string_type, input_value=404, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-offer-consents/{offerId}.put.responses.422.[key]
  Input should be a valid string [type=string_type, input_value=422, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-account-eligibility.get.responses.200.[key]
  Input should be a valid string [type=string_type, input_value=200, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-account-eligibility.get.responses.401.[key]
  Input should be a valid string [type=string_type, input_value=401, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-account-consent.put.responses.200.[key]
  Input should be a valid string [type=string_type, input_value=200, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-account-consent.put.responses.400.[key]
  Input should be a valid string [type=string_type, input_value=400, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-account-consent.put.responses.401.[key]
  Input should be a valid string [type=string_type, input_value=401, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type
paths./sale/allegro-prices-account-consent.put.responses.422.[key]
  Input should be a valid string [type=string_type, input_value=422, input_type=int]
    For further information visit https://errors.pydantic.dev/2.3/v/string_type

Przykład poprawnego rozwiązania ze swaggera:

 /parcel-management/delivery-services':
    get:
      tags:
        - Parcel management
      summary: "Get available delivery services"
      description: >-
        Use this resource to get delivery services available for user. It returns services provided by Allegro and contracts with carriers owned by user and configured by GUI. Read more: <a href="../../tutorials/jak-zarzadzac-przesylkami-przez-wysylam-z-allegro-LRVjK7K21sY#jak-pobrac-liste-uslug-dostawy" target="_blank">PL</a> / <a href="../../tutorials/how-to-manage-parcels-via-ship-with-allegro-ZM9YAyGKWTV#how-to-retrieve-a-list-of-delivery-services" target="_blank">EN</a>.
      operationId: getAvailableDeliveryServices
      responses:
        '200':
          description: OK
          content:
            application/vnd.allegro.public.v1+json:
              schema:
                $ref: '#/components/schemas/DeliveryServices'
        '401':
          description: Unauthorized
          content:
            application/vnd.allegro.public.v1+json:
              schema:
                $ref: '#/components/schemas/AuthError

[AureliuszBrussy]

Dziękuję za zwrócenie uwagi. Poprawiliśmy to.

[gitrid]

Czy używacie jakiegoś specjalnego configu do OpenAPI? Natykam się na bieżąco na rozbieżności ze standardem i zastanawiam się czy nie wynika to z mojej ignorancji/czegoś nie wiem. Wątpię, aby wszyscy manualnie tworzyli integrację zamiast korzystać ze swaggera i generatorów, a przy niezgodności z OpenAPI nie jest to możliwe.

Np. 1.

Invalid content_type returned. Content_type='application/vnd.allegro.public.v1+json; charset=UTF-8' was returned when only {'application/vnd.allegro.public.v1+json'} are defined for status_code=200

W poradnikach na stronie przykłady pokazują content_type z "charset=UTF-8", ale w dokumentacji (w związku z tym i w swaggerze) już nie. Zwracane odpowiedzi z tego powodu nie zgadzają się z oczekiwanymi.

2.

Invalid type. Required value type is frozendict and passed type was NoneClass at ['args[0]']['nextPage']

spowodowane przez:

    GetSaleProductsResponse:
      type: object
      required:
        - products
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/BaseSaleProductResponseDto'
        categories:
          $ref: '#/components/schemas/SaleProductResponseCategoriesDto'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ListingResponseFilters'
        nextPage:
          type: object
          properties:
            id:
              type: string
              description: A "cursor" to the next set of results.

nextPage nie jest required, czyli nie musi być zwracany, ale jeżeli jest, to musi być stringiem. API Allegro może zwrócić None. Standard OpenAPI wymaga, aby oznaczyć pole jako "nullable: true" (lub type 'null' w OpenAPI 3.1).

[AureliuszBrussy]

Z jakiej biblioteki do walidacji OpenAPI korzystasz? Spróbuję to wyjaśnić.

[gitrid]

Chyba najpopularniejszej, https://github.com/OpenAPITools/openapi-generator. Z góry dzięki za wsparcie.

[AureliuszBrussy]

Sprawdzamy to. Wkrótce wrócę z informacją.

[stale[bot]]

W tym wątku nie pojawiła się żadna nowa odpowiedź w ciągu 7 dni, dlatego automatycznie oznaczamy go jako przeterminowany. Jeśli w ciągu kolejnych 7 dni nie pojawi się żadna odpowiedź, wątek zostanie zamknięty. Dziękujemy za zaangażowanie w dyskusję i zachęcamy Cię do wypełnienia ankiety dotyczącej naszego wsparcia na forum.

---

There was no new reply in this thread within 7 days, therefore, we automatically marked it as expired. If no response is received within the next 7 days, this thread will be closed. Thank you for engaging in the discussion. We encourage you to complete our forum support survey.

[gitrid]

Będę wdzięczny za odpowiedź. Odpowiedzi API zmieniają się bardzo chaotycznie i wciąż wbrew deklarowanej specyfikacji OpenAPI. Zgodnie ze swaggerem, content type to application/vnd.allegro.public.v1+json. W moim poście powyzej, wskazywałem, że zamiast tego zwracane jest application/vnd.allegro.public.v1+json; charset=UTF-8. Tydzień temu odpowiedzi zostały zamienione na application/json; charset=UTF-8. Dzisiaj w nocy zmieniło się to znowu na application/json; charset=utf-8. 3 wersje w 2 tygodnie, żadna prawidłowa. To tylko przykład problemów, przydatna byłaby informacja jakiej specyfikacji się trzymacie lub z czego wynikają rozbieżności, aby devowie mogli sami ją dostosować.

[AureliuszBrussy]

Analizujemy to. Jak tylko coś się zmieni - wrócę z odpowiedzią.

[stale[bot]]

W tym wątku nie pojawiła się żadna nowa odpowiedź w ciągu 7 dni, dlatego automatycznie oznaczamy go jako przeterminowany. Jeśli w ciągu kolejnych 7 dni nie pojawi się żadna odpowiedź, wątek zostanie zamknięty. Dziękujemy za zaangażowanie w dyskusję i zachęcamy Cię do wypełnienia ankiety dotyczącej naszego wsparcia na forum.

---

There was no new reply in this thread within 7 days, therefore, we automatically marked it as expired. If no response is received within the next 7 days, this thread will be closed. Thank you for engaging in the discussion. We encourage you to complete our forum support survey.

[gitrid]

up, aby wątek się nie przeterminował

[AureliuszBrussy]

Tak, zapisałem tą sprawę, nie obawiaj się, wątek się nie usunie. Jak będę miał już kompletne informacje i podjęte działania - wrócę z informacją.