Improve API resourcedocs / swagger for PSD2 APIs

OpenBankProject / OBP-API

An open source RESTful API platform for banks that supports Open Banking, XS2A and PSD2 through access to accounts, transactions, counterparties, payments, entitlements and metadata - plus a host of internal banking and management APIs.

https://www.openbankproject.com/

1.54k stars 431 forks source link

Improve API resourcedocs / swagger for PSD2 APIs #199

Open simonredfern opened 7 years ago

simonredfern commented 7 years ago

Improve the specification coverage for PSD2 APIs

https://apiexplorersandbox.openbankproject.com/?version=2.1.0&psd2=true

So far: "Codes 200/400 are represented by only success and a missing "error" struct. Is it possible to get any further information on the types returned for each API."

hongwei1 commented 7 years ago

fixed in #511

chackett commented 7 years ago

Hi @hongwei1 thanks for responding to this.

Can you please outline has this has been fixed? From the above link I click on the Swagger docs at the very bottom. Previously that link brought me to a HTML page where I could view the documentation but now just returns a bunch of JSON. When I inspect that JSON I still see the responses are just 200 / 400 and the error schema is still missing.

FYIL This is the link I refer to which was previously HTML documentation:

https://apisandbox.openbankproject.com/obp/v1.4.0/resource-docs/v2.1.0/swagger?core=&psd2=true&obwg=

chackett commented 7 years ago

Perhaps I am browsing an endpoint that does not yet have this release deployed?

hongwei1 commented 7 years ago

@chackett Thanks for your message. Yes, the commit have not deployed on https://apisandbox.openbankproject.com server.

sebtesobe commented 7 years ago

@chackett The latest version of the API has been deployed to that server. Please check if your issue has been resolved.

chackett commented 7 years ago

Hi guys - It would appear that things have not changed. I still get a bunch of JSON back.

hongwei1 commented 7 years ago

@chackett click the following button: or: https://apisandbox.openbankproject.com/obp/v1.4.0/resource-docs/v3.0.0/swagger?core=&psd2=&obwg=

You can get the Swagger JSON.

Thanks for your feedback.

chackett commented 7 years ago

Thanks guys. I think this is still broken. There are a number of issues.

Way back in October I was at a OBP hackathon and clicking that link yielded a Swagger UI to browse the API documentation. Now it seems that is replaced by just a bunch of JSON. I was hoping to get a UI to enable me to browse the UI.
This bug relates to the lack of any meaningful response messages in the documentation, making it difficult for me to write a wrapper. Also the error struct is still missing. In the JSON from those links: ""$ref": "#/definitions/BanksJSON"" still exists.

hongwei1 commented 7 years ago

@chackett 1 you can copy the Swagger JSON to http://editor.swagger.io/#/ 2 we have provide the success body and error body as following :

"responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BanksJSON" } }, "400": { "description": "Error", "schema": { "$ref": "#/definitions/ErrorUnKnownError" } } }

what's wrong on "$ref": "#/definitions/BanksJSON""? They are the Swagger grammar stuff.

Would you like to join our slack ? We can support you immediately there. https://openbankproject.slack.com/messages
or https://slack.openbankproject.com/