search

PaystackOSS / openapi

The OpenAPI specification for the Paystack API
MIT License
15 stars 14 forks source link

Semantic error at paths./dedicated_account/split.delete.requestBody DELETE operations cannot have a requestBody #47

Open magoogli opened 5 days ago

magoogli commented 5 days ago

Hi, I have been trying to generate a client using sdk/paystack.yaml for .net by using the built in visual studio OPenAPI client generator but it is failing with an error. I opened the document in question in https://editor.swagger.io/ and I am also getting an error there.

Specifically: 'Semantic error at paths./dedicated_account/split.delete.requestBody DELETE operations cannot have a requestBody'

It would be great to see a workable swagger document but at the moment it doesn't appear possible to use this to generate a client - kind of nullifying its usefulness.

Steps to reproduce:

Go to: https://editor.swagger.io/ and paste in the contents of sdk/paystack.yaml

damilola-paystack commented 5 days ago

Hi @magoogli, thanks for bubbling this up. It was previously reported in issue #13. As stated in the previous issue, it requires an API change, not necessarily just the specification change. How are you planning to use the .NET SDK? Maybe we could find a way around the operation in question.

magoogli commented 5 days ago

Hi @damilola-paystack thank you for the quick response.

My backend is using the .Net stack and needs to communicate with PayStack.

I can use https://github.com/adebisi-fa/paystack-dotnet or https://github.com/developerslearnit/Paystack.Net.SDK as client libraries as a work around but I was hoping that given that you are providing an Open API Specification I would be able to use that as the source of truth for what the API can do, and generate a client library from the specification. After all that is the whole point of Open API - to make life easier to integrate by defining the API in a computer understandable and standard way.

Both of those libraries are maintained by a very few people, and after limited testing with one of them I fairly quickly discovered a bug - not something which inspires much confidence for a production ready application. If Paystack were to officially provide an Open API specification it would mitigate the need for these libraries in .Net or any other language for that matter that supports client generation from the Open API Spec.

Unfortunately it appears as you mentioned that the API itself is not technically correct and so the Open API spec is also broken...

If you have a look at https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.5 you will see that having a body for a Delete request is not good practice.

' A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.'

I would encourage your team to fix the underlying issue in the API and update the Open Api Spec.