[Bug 28463] New: Change spec for better looking in the docs
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Bug ID: 28463 Summary: Change spec for better looking in the docs Change sponsored?: --- Product: Koha Version: master Hardware: All OS: All Status: NEW Severity: enhancement Priority: P5 - low Component: REST API Assignee: koha-bugs@lists.koha-community.org Reporter: tomascohen@gmail.com Now that we are making our API spec public [1] we need to take care of little details we didn't consider. Some of them: - Our tags are all lower-case and single-worded, like illrequests - They lack descriptions (addSMTPServer could have some nicely written description like 'Add SMTP server'). - Our tags are 'tag cloud' oriented, as with SwaggerUI showing them with colors, but ReDoc uses them to organize the navigator, so they need to be cleaned. We cannot have 'patrons' and 'patron', it should just be one. -- You are receiving this mail because: You are watching all bug changes. You are the assignee for the bug.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |jonathan.druart+koha@gmail. | |com, | |kyle@bywatersolutions.com, | |martin.renvoize@ptfs-europe | |.com Assignee|koha-bugs@lists.koha-commun |tomascohen@gmail.com |ity.org | -- You are receiving this mail because: You are watching all bug changes. You are the assignee for the bug.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 --- Comment #1 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 121445 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=121445&action=edit Bug 28463: Add tags definitions in swagger.yaml This patch starts the work of curating the spec documentation-related aspects. It doesn't involve any functional change on the API, just labels (used to render docs) and some descriptions basis is added. - A top level 'tags' entry is added to swagger.yaml. - The 'name' attribute is left with double quotes. This is on purpose, to differentiate from 'x-displayName' which is the actual text to be displayer and should be handled by documentation folks, not us, devs :-D - I add a very limited 'description' attribute there. It is the top level description of the section. For example the description for the 'Biblios' section is 'Manage bibliographic records'. As it expects Markdown, anything we want can be added there. - Some labels have been tweaked in paths, to rollback the decision of making the labels in paths more end-user friendly. We don't want them to be typed much, and I picked what we use the most: snake_case. - The order in which things are displayed, is the one we specified on the swagger.yaml file. The 'batch import profiles' one is left at the bottom on purpose. But this is subject to discussion. As a general rule, I put them all in alphabetical order (on the x-displayName label I mean). I submit early before family duties so others can pick where I left in the morning. So: TODO: - I'm not sure what's best for Advanced editor macros. My bet is we should define a 'Macros' label, and use a summary on the routes themselves to specify this are not just 'macros', but advanced editor macros. Look at the return claims paths to understand how I propose to use the 'summary' attribtue. - I understand how we use 'rotas', but someone more familiar with the terminology,... please... step in. - Related to the first item here, we need to add summary to all routes, so ReDoc doesn't display the operationId anymore. Again, I put an example in Return claims that we can follow. To test: 1. Have KTD running 2. Open your browser at: http://localhost:/8080/api/v1/ 3. Save the page as spec.json in some known dir 4. Go to that dir and run: $ docker run -it --rm -p 8083:80 \ -v $(pwd)/spec.json:/usr/share/nginx/html/swagger.json \ -e SPEC_URL=swagger.json redocly/redoc 5. Open your browser at http://localhost:8083 => SUCCESS: You see the docs 6. Look at the list of 'categories' on the left => FAIL: They look a bit weird 7. Apply this patch 8. Ctrl+c on the terminal running docker 9. Reload plack 10. Repeat 2 through 6 => SUCCESS: Wow, things look better! 11. Sign off :-D Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Jonathan Druart <jonathan.druart+koha@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Keywords| |rel_21_05_candidate -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 --- Comment #2 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 121450 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=121450&action=edit Bug 28463: Add missing tags This patch adds entries for: - Rotas - Circulation rules - Macros Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 --- Comment #3 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 121451 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=121451&action=edit Bug 28463: Add summary to all routes This patch adds a 'summary' entry to all routes and verbs. This way, ReDoc will display a human-friendly description of the route, instead of the operationId. To test, repeat the testing steps in the previous patch, and notice that we now have good descriptions. Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- QA Contact| |martin.renvoize@ptfs-europe | |.com CC| |agustinmoyano@theke.io, | |katrin.fischer@bsz-bw.de, | |nick@bywatersolutions.com -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |Needs Signoff -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Kyle M Hall <kyle@bywatersolutions.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|Needs Signoff |Signed Off -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Kyle M Hall <kyle@bywatersolutions.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #121445|0 |1 is obsolete| | Attachment #121450|0 |1 is obsolete| | Attachment #121451|0 |1 is obsolete| | --- Comment #4 from Kyle M Hall <kyle@bywatersolutions.com> --- Created attachment 121453 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=121453&action=edit Bug 28463: Add tags definitions in swagger.yaml This patch starts the work of curating the spec documentation-related aspects. It doesn't involve any functional change on the API, just labels (used to render docs) and some descriptions basis is added. - A top level 'tags' entry is added to swagger.yaml. - The 'name' attribute is left with double quotes. This is on purpose, to differentiate from 'x-displayName' which is the actual text to be displayer and should be handled by documentation folks, not us, devs :-D - I add a very limited 'description' attribute there. It is the top level description of the section. For example the description for the 'Biblios' section is 'Manage bibliographic records'. As it expects Markdown, anything we want can be added there. - Some labels have been tweaked in paths, to rollback the decision of making the labels in paths more end-user friendly. We don't want them to be typed much, and I picked what we use the most: snake_case. - The order in which things are displayed, is the one we specified on the swagger.yaml file. The 'batch import profiles' one is left at the bottom on purpose. But this is subject to discussion. As a general rule, I put them all in alphabetical order (on the x-displayName label I mean). I submit early before family duties so others can pick where I left in the morning. So: TODO: - I'm not sure what's best for Advanced editor macros. My bet is we should define a 'Macros' label, and use a summary on the routes themselves to specify this are not just 'macros', but advanced editor macros. Look at the return claims paths to understand how I propose to use the 'summary' attribtue. - I understand how we use 'rotas', but someone more familiar with the terminology,... please... step in. - Related to the first item here, we need to add summary to all routes, so ReDoc doesn't display the operationId anymore. Again, I put an example in Return claims that we can follow. To test: 1. Have KTD running 2. Open your browser at: http://localhost:/8080/api/v1/ 3. Save the page as spec.json in some known dir 4. Go to that dir and run: $ docker run -it --rm -p 8083:80 \ -v $(pwd)/spec.json:/usr/share/nginx/html/swagger.json \ -e SPEC_URL=swagger.json redocly/redoc 5. Open your browser at http://localhost:8083 => SUCCESS: You see the docs 6. Look at the list of 'categories' on the left => FAIL: They look a bit weird 7. Apply this patch 8. Ctrl+c on the terminal running docker 9. Reload plack 10. Repeat 2 through 6 => SUCCESS: Wow, things look better! 11. Sign off :-D Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io> Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 --- Comment #5 from Kyle M Hall <kyle@bywatersolutions.com> --- Created attachment 121454 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=121454&action=edit Bug 28463: Add missing tags This patch adds entries for: - Rotas - Circulation rules - Macros Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io> Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 --- Comment #6 from Kyle M Hall <kyle@bywatersolutions.com> --- Created attachment 121455 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=121455&action=edit Bug 28463: Add summary to all routes This patch adds a 'summary' entry to all routes and verbs. This way, ReDoc will display a human-friendly description of the route, instead of the operationId. To test, repeat the testing steps in the previous patch, and notice that we now have good descriptions. Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io> Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Jonathan Druart <jonathan.druart+koha@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|Signed Off |Passed QA -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Jonathan Druart <jonathan.druart+koha@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Version(s)| |21.05.00 released in| | Status|Passed QA |Pushed to master -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 --- Comment #7 from Jonathan Druart <jonathan.druart+koha@gmail.com> --- Pushed to master for 21.05, thanks to everybody involved! -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 Jonathan Druart <jonathan.druart+koha@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Keywords|rel_21_05_candidate | -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28463 David Cook <dcook@prosentient.com.au> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |dcook@prosentient.com.au -- You are receiving this mail because: You are watching all bug changes.
participants (1)
-
bugzilla-daemon＠bugs.koha-community.org