Issue #546 - Formmat swagger.json file

[marcelojaloto]

Formmat swagger.json file for when needed to investigat in the Swagger Editor.

View issue #546

[marcelojaloto]

@danieleteti I took your master branch and didn't find this fix.
What happened?

[danieleteti]

The "Format" call has been removed because on a very big swagger it raises exceptions for a user. Using the plain "ToJSON" he solved the problem. I'm still trying to get the sample Swagger to do a better test.

[danieleteti]

This is the user comment in the facebook group

[marcelojaloto]

@danieleteti
Sooner or later your swagger will pop again. The problem with this has another solution.

Is it possible to generate a giant swagger so I can collaborate on a new solution, but keeping the Json.Format?

[claudio-piffer]

Hi @marcelojaloto

I'm the user that has reported the problem. If you want I can send you the json that generates DMVC without formatting. My swagger documentation has big summary description. If I disable all the controllers and enable them one at a time, the documentation is generated correctly. Unfortunately I have not yet had time to investigate the problem (I'm releasing a very important version of the application) but the suspicion is that the formatter has some problems when there is a lot of documentation. I'm available for any tests or support you need. Since the documentation is "private" I ask you an email address to send you the file.

[marcelojaloto]

Hi @claudio-piffer

I can help you. I have a knowledge of Swagger and am the creator of SwagDoc for Delphi.

Please send the file to my email. OK?

[email protected]

[claudio-piffer]

Hi @marcelojaloto

thank you very much! I just send to you the email with generated json.

[marcelojaloto]

@claudio-piffer

I received the file.

There are several semantic errors. And it needs to be evaluated one by one.

Open the DMVC_Swagger.json file in the Swagger Editor:

https://editor.swagger.io/

errors

Structural error at paths./api/patients.delete.parameters.0
should NOT have additional properties
additionalProperty: type
Jump to line 26

Semantic error at paths./api/patients.delete.security.0
Security requirements must match a security definition
Jump to line 47

Semantic error at paths./api/patients/source/{sourceName}/healthcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}.put.security.0
Security requirements must match a security definition
Jump to line 97

Semantic error at paths./api/patients/source/{sourceName}/healthcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}.post.security.0
Security requirements must match a security definition
Jump to line 148

Semantic error at paths./api/patients/source/{sourceName}/healthcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}/slave.delete.security.0
Security requirements must match a security definition
Jump to line 196

Semantic error at paths./api/patients/source/{sourceName}/healthcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}/slave.put.security.0
Security requirements must match a security definition
Jump to line 247

Structural error at paths./api/patients/source/{sourceName}/healtcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}/status/{status}.put.parameters.4
should NOT have additional properties
additionalProperty: type
Jump to line 289

Semantic error at paths./api/patients/source/{sourceName}/healtcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}/status/{status}.put.security.0
Security requirements must match a security definition
Jump to line 317

Semantic error at paths./api/orders/source/{sourceName}/healthcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}.put.security.0
Security requirements must match a security definition
Jump to line 367

Semantic error at paths./api/orders/source/{sourceName}/healthcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}.post.security.0
Security requirements must match a security definition
Jump to line 416

Semantic error at paths./api/report/source/{sourceName}/healthcare/companies/{companyCode}/structures/{structureCode}/authority/{authorityCode}.post.security.0
Security requirements must match a security definition
Jump to line 462

Semantic error at paths./api/events/order/authority/{authority}/timestampUTC/{timestampUTC}/countryCode/{countryCode}/orderId/{orderID}.get.security.0
Security requirements must match a security definition
Jump to line 512

Semantic error at paths./api/events/documents/destination/{destinationName}/count/{eventCount}.get.security.0
Security requirements must match a security definition
Jump to line 548

Semantic error at paths./api/events/patients/destination/{destinationName}/count/{eventCount}.get.security.0
Security requirements must match a security definition
Jump to line 584

Semantic error at paths./api/events/reports/destination/{destinationName}/count/{eventCount}.get.security.0
Security requirements must match a security definition
Jump to line 620

Semantic error at paths./api/events/orders/destination/{destinationName}/count/{eventCount}.get.security.0
Security requirements must match a security definition
Jump to line 656

Semantic error at paths./api/events/destination/{destinationName}/eventId/{eventId}/status.put.security.0
Security requirements must match a security definition
Jump to line 694

Semantic error at paths./api/patientcd/orders/uuid/{orderUUID}/status.post.security.0
Security requirements must match a security definition
Jump to line 731

Semantic error at paths./api/events/patientcd/destination/{destinationName}/count/{eventCount}.get.security.0
Security requirements must match a security definition
Jump to line 769

Semantic error at paths./api/events/configuration/companies/{companyCode}/structures/{structureCode}/destinations/{destinationName}/authority/{destinationAuthorityCode}.put.security.0
Security requirements must match a security definition
Jump to line 822

[marcelojaloto]

@claudio-piffer

I try to check each error, but I will send you the corrected file.

However for each error corrected for you will need to compare the json with and error and corrected to solve in your code each error found.

Unfortunately I don't have yours source code to help you. If you can't, if it is of interest to you, we can arrange a consultation to help you.

ok?

[marcelojaloto]

@claudio-piffer

In summary, two types of errors occur at various points, and to solve it, simply remove the points in the source code and your file will open normally with the formatted option.

1- For parameters of type body, there is no place to put the field "type: array". Remove it and it will be fixed.

      parameters:
        - in: body
          name: patientIdentifierRepresentation
          description: Identificativi dei pazienti
          required: true
          schema:
            $ref: '#/definitions/PatientIdentifierRepresentation'
          type: array

2- The empty security requirements cannot be passed. Remove it and it will be fixed.

      security:
        - bearer: []

[marcelojaloto]

@danieleteti

The API swagger file sent to me is relatively very small compared to others I know, the fact that it is formatted is not the reason for the problem. When the file is formatted, it allows Swagger UI to check for semantic errors. And when there are semantic errors the file is not loaded by the Swagger UI. This is good because it doesn't hide problems that need to be fixed. The swagger file is not formatted, you live with hidden problems that can cause you trouble without knowing where they are occurring.

It is very important that the swagger.json file be formatted in DMVC.

Are you in agreement?

[claudio-piffer]

Hi Marcelo

thank you very much but the JSON is generated from DMVC not from me. The file that I sended is the result of the swagger documentation generated from header method attributes of my controllers.

Example: in api/patient the ClosePositionPatient swagger is generated from this:

I had already seen that if I paste json in editor.swagger.io this raise many semantic error. But since the documentation is generated through the attributes, the library should manage the correct generation. Right?

Best Regards

[claudio-piffer]

e API swagger file sent to me is relatively very small compared to others I know, the fact that it is formatted is not the rea

Hi Marcelo,

my service is deployed with Apache http and swagger is integrated into my DMVC service. If I generate swagger documentation without formatter all work fine. With formatter don't work.

I modified MVCFramework.Middleware.Swagger

I run the local service and open swagger doc this is result

Whit the original code (with formatter):

The only difference is the formatted json and the problem (in general) is not the json otherwise it would raise an error even if not formatted.

The semantic errors (which I had already seen too) are to be found in the json generation code. As soon as I free myself a little from daily activities, I investigate.

Best Regards ;-)

[marcelojaloto]

Hi Marcelo

thank you very much but the JSON is generated from DMVC not from me. The file that I sended is the result of the swagger documentation generated from header method attributes of my controllers.

Example: in api/patient the ClosePositionPatient swagger is generated from this:

I had already seen that if I paste json in editor.swagger.io this raise many semantic error. But since the documentation is generated through the attributes, the library should manage the correct generation. Right?

Best Regards

@claudio-piffer

It is not the responsibility of the library to do the semantic validations because the swagger UI already does.

The "type: array" problem can be seen in the figure below.

[marcelojaloto]

@claudio-piffer

why do you use a body with DELETE verb? Maybe you have other problems with this.

Regarding the other error: "security: -bearer" needs to find where you add this. The library does not forcefully add this. This is manually added.

On the issue of formatted json I had already explained that the Swagger UI only does the validations if the file is formatted. Probably the generated swagger.json has some error that can be observed in the Swagger Editor.

Tip: Look for the word 'bearer' in your source code or in your version of DMVC.

[claudio-piffer]

@marcelojaloto

why do you use a body with DELETE verb? Maybe you have other problems with this.

The specifications are of my customer. I agree with you. There are some things I disagree but unfortunately I cannot change anything on this point. The customer has validated these specifications and I have to abide by

Regarding the other error: "security: -bearer" needs to find where you add this. The library does not forcefully add this. This is >>manually added.

Tip: Look for the word 'bearer' in your source code or in your version of DMVC.

In my code no! I use last git original version of the DMVC. In source DMVC the bearer is found in MVCFramework.pas and MVCFramework.Middleware.JWT.pas

On the issue of formatted json I had already explained that the Swagger UI only does the validations if the file is formatted. >>Probably the generated swagger.json has some error that can be observed in the Swagger Editor.

ok!

Thank you very much for your support!!! I appreciate it!

[claudio-piffer]

Hi @marcelojaloto

I have noticed this though. In debug I save the formatted json before render and try to validate it with https://jsonformatter.curiousconcept.com but it raises a lot of errors.

If instead I paste the unformatted json it is validated correctly

[claudio-piffer]

If I paste the yaml specification that my customer has validated in editor.swagger.io it does not report any problem with an array parameter in the body on the DELETE verb

[marcelojaloto]

@claudio-piffer

In the corrected swagger.json file that I sent you by email, use the example with Format and you will see that the swagger UI will load its API normally. This will prove to you what I've been saying. You are generating a swagger.json with some semantic problems and once the file is formatted Swagger UI will check for inconsistencies and then your documentation will not be loaded. The great advantage of this option being activated is that it discovers the problems with each test that is carried out and does not leave hidden problems. As you have been using this option without formatting you have accumulated a lot of errors to fix at the moment, but filtering the errors are just two types of errors that you need to resolve.