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* <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 -- You received this message because you are subscribed to the Google Groups "Swagger" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
