swagger-api / swagger-api/swagger-ui

Resolve enum objects in swagger UI

Open
#5,893 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: support
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Content & configuration
swagger: "2.0"
info:
  description: "This is the description of the wanted view of a swagger definition"
  version: "1"
  title: "Enum Demo"
  
paths:
  /getPymentInfo:
    get:
      description: gets a payment information of one type
      produces:
        - application/json
      responses:
        '200':
          description: What should I say
          schema:
            $ref: '#/definitions/PaymentInformation'



 
definitions:
  paymentMethod:
    description: Eine Auswahl an Bezahlmethoden. Aufbau siehe CreditCardPaymentMethod, DirectDebitPaymentMethod und PayPalPaymentMethod
    type: object 
    enum:
      - $ref: '#/definitions/CreditCardPaymentMethod'
      - $ref: '#/definitions/DirectDebitPaymentMethod'
      - $ref: '#/definitions/PayPalPaymentMethod'

  Date:
    type: string
    format: 'yyyy-MM-ddTHH:mm:ssZ'
    description: 'Datumsdefinition im ISO 8601 Format'
  
  Name:
    type: string
    maxLength: 100
    description: 'Basisdefinition für ein Namensattribut'


  PaymentInformation:
    allOf:     # Vererbung
      - type: object
      - description: demonstration object
      - properties:
          paymentMethod:
            description: Eine Bezahlmethode. Die Auswahl lässt sich im Swagger nicht darstellen
            $ref: '#/definitions/paymentMethod'

                
  PaymentMethod:
    type: object
    description: Master Object for easier inheritence
    properties:
      id:
        type: integer
        maxLength: 20
        format: "int64"
      modifyDate:
        $ref: '#/definitions/Date'
        # description: 'Das letzte änderungsdatum'
    required:
      - id
      - modifyDate

  CreditCardPaymentMethod:
    type: object
    allOf:     # Vererbung
      - $ref: '#/definitions/PaymentMethod'
      - description: Struktur einer Kreditkarteninformation
      - properties:
          number:
            type: string
            maxLength: 20
            description: Kartennummer
          ownerName:
            $ref: '#/definitions/Name'
            description: Name des Kreditkarteninhabers
          testNumber:
            type: integer
            maxLength: 10
            description: Prüfnummer
          status:
            type: integer
            maxLength: 1
            enum:
              - -1: Abgelehnt
              - 0: Neu
              - 1: Akzeptiert
            description: Status der Kreditkarte, ob geprüft oder nicht
    required:
      - number
      - ownerName
      - testNumber
      - status
      
  DirectDebitPaymentMethod:
    type: object
    allOf:     # Vererbung
      - $ref: '#/definitions/PaymentMethod'
      - description: Struktur Abbuchungsinformationen
      - properties:
          iban:
            type: string
            maxLength: 50
            description: Die IBAN des Kontos
          bic:
            type: string
            maxLength: 20
            description: Die BIC des Kontos
          institute:
            $ref: '#/definitions/Name'
            description: Name des Bankhauses
          agreementAccepted:
            type: boolean
            description: Kenner, dass der Nutzer die Nutzungsbedingungen akzeptiert hat
          status:
            type: integer
            maxLength: 1
            enum:
              - -1: Abgelehnt
              - 0:  Neu
              - 1:  Akzeptiert
            description: Status des Kontos, ob geprüft oder nicht
    required:
      - iban
      - bic
      - institute
      - agreementAccepted
      - status

  PayPalPaymentMethod:
    type: object
    allOf:     # Vererbung
      - $ref: '#/definitions/PaymentMethod'
      - description: Struktur einer PayPalinformation
      - properties:
          mail:
            type: string
            maxLength: 100
            description: Die Mailadresse bei PayPal
          password:
            type: string
            maxLength: 100
            description: Passwort zur Adresse
          status:
            type: integer
            maxLength: 1
            enum:
              - -1: Abgelehnt
              - 0:  Neu
              - 1:  Akzeptiert
            description: Status der Kreditkarte, ob geprüft oder nicht
    required:
      - mail
      - password
      - status
Is your feature request related to a problem?

The problem is a communication problem because the real content of the communication is not visible. What I want (in the example above) is to see that the response includes one of the three defined objects (credit card, direct debit or pay pal). At the moment there is no error but the content is not complete.
This is the actual result:

{
  "paymentMethod": {}
}
Describe the solution you'd like

I would like to see something like this (if it is the real structure):

{
  "paymentMethod": {
      CreditCardPaymentMethod: {
        "id": 0,
        "modifyDate": "string",
        "number": "string",
        "ownerName": "string",
        "testNumber": 0,
        "status": {
        "-1": "Abgelehnt"
        }
     }
  }
}
Describe alternatives you've considered

I do not see any alternative. And I tried a lot for example with oneOf.

Additional context

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the supplied Swagger 2.0 definition in Swagger UI, focusing on the paymentMethod enum of object references and the nested status enums. Compare the generated response example with the requested representation, and consider the feature complete when the UI visibly represents the possible payment method objects and their fields without losing the enum information.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.