PDF-generation via swagger2Markup and field description issue $ Ref: #’/definitions …..

[vala.anna.kla...@arcor.de]

Today I would like to ask you a question. The background is that we are currently documenting the individual APIs

Parameters and fields and their business usage.  We are using the Swagger editor to edit our YAML.

It will then be used to generate the source code and in addition we are using functions from the swagger2markup

(https://github.com/Swagger2Markup/swagger2markup) Project to generate a PDF file, which will be provided to our consumers as a

kind of API business documentation.

Unfortunately, the content of the generated PDF file is causing difficulties for the consumer when they attempt to use it and I have not been able to find a solution.

Here are the issues the consumer is experiencing when attempting to read the PDF file:

1.) When creating a PDF file out of the YAML-File though the SWAGGER editor, the data fields (parameters) are shown in alphabetical order,

which can cause some confusion for the reader of the PDF file.

Question:  Is there a way the reordering of the data field (parameter) can be suppressed when generating a PDF?

 

2.) We have an object called ‘amount’ which points to $ Ref: '# / definitions / Amount'

Example:
  

    currentBalance:
        $ Ref: '# / definitions / Amount'
     lastBookingDayBalance:
        $ Ref: '# / definitions / Amount'

 

 

(definitions:...)

Amount:

    type: object

    description: currently I only see a possiblity to placed the desciption here e.g. currentBalance …….lastBookingDayBalance…

    properties:

      value:

        type: string

        description: >-

      numberOfDecimals:

        type: integer

        format: int32

      currencyCode:

        type: string

        description:

 

Question:  Is there a way that we can provide a business description of the certain amount types next to, below or above the various amount parameter(s)?

     currentBalance:
        $ Ref: '# / definitions / Amount'
     lastBookingDayBalance:
        $ Ref: '# / definitions / Amount'

We can add a description in the definitions /Amount, but from a consumer point of view this is not really handy.

Reading the PDF file, the consumer does not expect that the description of certain parameters are shown somewhere in the PDF file. 

 

The Data field amount indicates an amount. However, there are different business usages of the amount such as

CurrentBalance, lastBookingDayBalance, and so on.

The only thing that the amount fields have in common is the structure of the amount itself (value, currency, decimals),

but not the business usage.

 

I could not find a solution on the internet which could solve the problem.  If there is no other solution, we will need to change the behavior of referencing on

parameters/objects, which will involve an enormous effort.  Unfortunately, we can not afford a change to our YAML-Files at this stage.

 

In addition, the amount field is one of many fields where we are facing this situation.

 

Any ideas of how to tackle this situation would be greatly appreciated.  Thanks for your support in this matter.
Vala

 

[marone]

Hey I wanted to update this. Basically is it possible to additional description on the same level as references?

currentBalance:

  description: 'specific description'

  $ Ref: '# / definitions / Amount'

This would allow us to describe multiple instances of the same model. Do you think it is possible to implement something along those lines and how hard / time costly would it be?