https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=16699
--- Comment #3 from Lari Taskula <[email protected]> --- Created attachment 52375 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=52375&action=edit Bug 16699: Split parameters and paths in Swagger Parameters and paths should be split in our Swagger specification, because otherwise swagger.json would become messy with all the paths and their further specification in the same file. Also parameters should be split for the same reason. Instead of using index.json for definitions, parameters and paths, we define new files "definitions.json", "parameters.json" and "paths.json" in order to simplify the references. If we kept using index.json and try to reference "/definitions/error.json" from "/paths/holds.json", reference would be "../definitions/index.json#/error" instead of now simplified version, "../definitions.json#/error". Here is the proposed structure: . ├── swagger.json ├── definitions.json ├── paths.json ├── parameters.json ├── definitions │ └── error.json │ └── patron.json ├── parameters │ └── patron.json ├── paths │ └── patrons.json ├── minifySwagger.pl └── swagger.min.js The swagger.json paths, definitions and parameters will look as follows: ... "paths": { "$ref": "paths.json" }, "definitions": { "$ref": "definitions.json" }, "parameters": { "$ref": "parameters.json" } ... A problem with splitting specification into multiple files directly from swagger.json (e.g. "paths": { "$ref": "paths.json" }) is that it is not following the Swagger specification and an error will be thrown by the Swagger-UI default validator (online.swagger.io/validator). To overcome this problem, we use the minifySwagger.pl script from Bug 16212. This allows the developers to work with the structure introduced in this patch thus allowing developers to split the specification nicely, and still have a valid Swagger specification in the minified swagger.min.json. To test: -2: Apply the minifier-patch in Bug 16212. -1: Make sure you can validate your specification with Swagger2 validator at online.swagger.io/validator/debug?url=url_to_swaggerjson, or install it locally from https://github.com/swagger-api/validator-badge. 1. Don't apply this patch yet, but first validate swagger.json with swagger.io-validator (or your local version, if you installed it) 2. Observe that validation errors are given 3. Run minifySwagger.pl 4. Validate swagger.min.json with the validator you used in step 1 5. Observe that validation passes and we overcame the invalid specification problem in swagger.min.json 6. Apply this patch 7. Run minifySwagger.pl 8. Repeat step 4 9. Observe that validation passes with new structure 10. Run REST tests at t/db_dependents/api/v1 (11. Study the new structure of our Swagger specifications :)) -- You are receiving this mail because: You are watching all bug changes. You are the assignee for the bug. _______________________________________________ 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/
