https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=15126
Olli-Antti Kivilahti <[email protected]> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |[email protected] --- Comment #5 from Olli-Antti Kivilahti <[email protected]> --- Hi! I think your solution looks robust and extendable. I would push the separation of definitions a bit further. This is a good article about how to split the Swagger2-spec: http://azimi.me/2015/07/16/split-swagger-into-smaller-files.html and it is pretty much the same as you did. How about we modified your suggestion so the structure looks like this: . ├── swagger.json ├── info │ └── index.json ├── definitions │ └── index.json │ └── error.json │ └── patron.json ├── parameters │ └── index.json │ └── patron.json └── paths ├── index.json └── patrons.json where definitions/patron.json looks like this: "borrower": { "type": "object", "properties": { "borrowernumber": { "$ref": "#/definitions/borrowernumber" }, "cardnumber": { "$ref": "#/definitions/cardnumber" }, "surname": { "$ref": "#/definitions/surname" }, "firstname": { "$ref": "#/definitions/firstname" }, ... } }, "cardnumber": { "description": "Library assigned ID number for Borrowers", "type": "string" }, "borrowernumber": { "type": "integer", "description": "Borrower internal identifier" }, "surname": { "description": "borrower's last name", "type": "string" }, "surname": { "description": "borrower's first name", "type": "string" } Now that there is a clear separation of logic (and release from insanely obscure git conflict resolutions with swagger.json), we should enforce that we define all parameters and definitions globally under #/parameters and #/definitions instead of defining them under object/path definitions. This way we maximize code reuse. In some cases it might not make much sense (if we only focus on today), like for "surname" and "firstname" in the above example, but some day in the near future somebody might want to reuse those components and then he would have to refactor those changes (or more likely just duplicate code because we are lazy). So as a future-proof solution I feel global definitions are the way to go. We could even push this a bit further, by instead of defining these REST API with the restrictions of the Koha DB, we could use commonly acknowledged linked data schemas, like schema.org to define our objects. https://schema.org/Person This would make it much easier to share the same records, for example between multiple Koha installations. Mainly because of the unique identifier in these objects, like {"url": "https://renki.vaarakirjastot.fi/api/v1/patrons/43441"} This is actually something which is easily enabled due to our awesome REST API and helps build more linked data systems between various API consumers. So if somebody would take our Patron-object, it would have a undeniably unique identifier and wouldn't conflict with Patron-objects originating from other systems. But for now we can focus on splitting our Swagger-spec. -- You are receiving this mail because: You are watching all bug changes. _______________________________________________ Koha-bugs mailing list [email protected] http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-bugs website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
