[Bug 34387] New: API docs tags missing descriptions
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Bug ID: 34387 Summary: API docs tags missing descriptions Change sponsored?: --- Product: Koha Version: master Hardware: All OS: All Status: NEW Severity: normal Priority: P5 - low Component: REST API Assignee: koha-bugs@lists.koha-community.org Reporter: tomascohen@gmail.com CC: tomascohen@gmail.com It is easy to spot the issue by entering [here](https://api.koha-community.org/Development.html). On the left column, some tags are nicely translated into descriptions (e.g. 'SMTP servers') and some others are not (e.g. 'search_filters'). We need to solve it, and enforce it at QA. -- 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=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |martin.renvoize@ptfs-europe | |.com -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Patch complexity|--- |String patch Status|NEW |Needs Signoff -- 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=34387 --- Comment #1 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 153891 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=153891&action=edit Bug 34387: Improve API docs naming consistency This patch aims to make our API docs be more consistent. It addresses two particular things: * There's no consistency on the `tags` used across the spec, and not all of them are correctly described and have an `x-displayName` entry. More on this later. * This are not sorted either by some for of grouping, or at least alphabetically. For the former, I did my best trying to harmonize (specially on the ERM front) with what we do in the rest of the use cases. For the latter, I opted for sorting everything alphabetically, as a first step. Hoping someone else could work on grouping things. To test (ON YOUR HOST MACHINE): 1. On current master run: $ cd api/v1/swagger $ docker run --rm -v $(pwd):/api --workdir /api redocly/cli \ build-docs swagger.yaml --output index.html => SUCCESS: It doesn't break or anything 2. Open your browser, open the generated api/v1/swagger/index.html file => FAIL: The left column has * several lower case entries * not everything is correctly grouped (ERM? packages?) * Things are not sorted. There's an attempt but looks messy 3. Apply this patch 4. Repeat 1 and 2 => SUCCESS: Things look much better! 5. Sign off :-D CAVEAT1: I'm not sure why, but import_batches doesn't work. Ideas are welcome, I'll keep looking for fixes. CAVEAT2: I don't have enough eHoldings background to weight in, but I feel like 'ERM eHoldings packages' could just be 'ERM packages'. Follw-up patches with better ideas are welcome. CAVEAT3: Patron credits, debits, balance... They could all go in to 'Patrons accounts' or similar. Open to ideas. CAVEAT4: Old redocly didn't support mapping an endpoint to more than one target section. Something to explore if we want (for example) to reach 'credits' through the 'Patrons' section but also from 'Accounting'. -- You are receiving this mail because: You are the assignee for the bug. You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- 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=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |caroline.cyr-la-rose@inlibr | |o.com, | |jonathan.druart+koha@gmail. | |com Keywords| |Manual -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Martin Renvoize <martin.renvoize@ptfs-europe.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #153891|0 |1 is obsolete| | --- Comment #2 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- Created attachment 153894 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=153894&action=edit Bug 34387: Improve API docs naming consistency This patch aims to make our API docs be more consistent. It addresses two particular things: * There's no consistency on the `tags` used across the spec, and not all of them are correctly described and have an `x-displayName` entry. More on this later. * This are not sorted either by some for of grouping, or at least alphabetically. For the former, I did my best trying to harmonize (specially on the ERM front) with what we do in the rest of the use cases. For the latter, I opted for sorting everything alphabetically, as a first step. Hoping someone else could work on grouping things. To test (ON YOUR HOST MACHINE): 1. On current master run: $ cd api/v1/swagger $ docker run --rm -v $(pwd):/api --workdir /api redocly/cli \ build-docs swagger.yaml --output index.html => SUCCESS: It doesn't break or anything 2. Open your browser, open the generated api/v1/swagger/index.html file => FAIL: The left column has * several lower case entries * not everything is correctly grouped (ERM? packages?) * Things are not sorted. There's an attempt but looks messy 3. Apply this patch 4. Repeat 1 and 2 => SUCCESS: Things look much better! 5. Sign off :-D CAVEAT1: I'm not sure why, but import_batches doesn't work. Ideas are welcome, I'll keep looking for fixes. CAVEAT2: I don't have enough eHoldings background to weight in, but I feel like 'ERM eHoldings packages' could just be 'ERM packages'. Follw-up patches with better ideas are welcome. CAVEAT3: Patron credits, debits, balance... They could all go in to 'Patrons accounts' or similar. Open to ideas. CAVEAT4: Old redocly didn't support mapping an endpoint to more than one target section. Something to explore if we want (for example) to reach 'credits' through the 'Patrons' section but also from 'Accounting'. Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #3 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- Created attachment 153895 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=153895&action=edit Bug 34387: (follow-up) Minor spelling and quoting fixes Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #4 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- *** Bug 34278 has been marked as a duplicate of this bug. *** -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #5 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- This is a great improvement.. * I couldn't work out why import_batches isn't working either.. very strange. * I'll ask Matt/Jonathan to comment on the ERM stuff * I'd love to see us use grouping later, but I don't think our redocly versions support it yet (and likely it'll all work better with the next swagger too) * The patron accounting endpoints feel like they need some cleaning up.. they're not all that consistent right now. All in all, I think this is a great starting point.. we should probably add some qa rules and accompanying tools around ensuring tagging takes place going forward. I think we should probably go with what's here for now and keep refining in other bugs. -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Martin Renvoize <martin.renvoize@ptfs-europe.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=34387 Katrin Fischer <katrin.fischer@bsz-bw.de> 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=34387 Katrin Fischer <katrin.fischer@bsz-bw.de> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #153894|0 |1 is obsolete| | --- Comment #6 from Katrin Fischer <katrin.fischer@bsz-bw.de> --- Created attachment 154065 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154065&action=edit Bug 34387: Improve API docs naming consistency This patch aims to make our API docs be more consistent. It addresses two particular things: * There's no consistency on the `tags` used across the spec, and not all of them are correctly described and have an `x-displayName` entry. More on this later. * This are not sorted either by some for of grouping, or at least alphabetically. For the former, I did my best trying to harmonize (specially on the ERM front) with what we do in the rest of the use cases. For the latter, I opted for sorting everything alphabetically, as a first step. Hoping someone else could work on grouping things. To test (ON YOUR HOST MACHINE): 1. On current master run: $ cd api/v1/swagger $ docker run --rm -v $(pwd):/api --workdir /api redocly/cli \ build-docs swagger.yaml --output index.html => SUCCESS: It doesn't break or anything 2. Open your browser, open the generated api/v1/swagger/index.html file => FAIL: The left column has * several lower case entries * not everything is correctly grouped (ERM? packages?) * Things are not sorted. There's an attempt but looks messy 3. Apply this patch 4. Repeat 1 and 2 => SUCCESS: Things look much better! 5. Sign off :-D CAVEAT1: I'm not sure why, but import_batches doesn't work. Ideas are welcome, I'll keep looking for fixes. CAVEAT2: I don't have enough eHoldings background to weight in, but I feel like 'ERM eHoldings packages' could just be 'ERM packages'. Follw-up patches with better ideas are welcome. CAVEAT3: Patron credits, debits, balance... They could all go in to 'Patrons accounts' or similar. Open to ideas. CAVEAT4: Old redocly didn't support mapping an endpoint to more than one target section. Something to explore if we want (for example) to reach 'credits' through the 'Patrons' section but also from 'Accounting'. Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Katrin Fischer <katrin.fischer@bsz-bw.de> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #153895|0 |1 is obsolete| | --- Comment #7 from Katrin Fischer <katrin.fischer@bsz-bw.de> --- Created attachment 154066 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154066&action=edit Bug 34387: (follow-up) Minor spelling and quoting fixes Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #8 from Katrin Fischer <katrin.fischer@bsz-bw.de> --- Created attachment 154067 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154067&action=edit Bug 34387: (QA follow-up) Fix disply of 'Import batches' Fixes the heading and sidebar display of the 'Import batches' section. Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #9 from Tomás Cohen Arazi <tomascohen@gmail.com> --- (In reply to Katrin Fischer from comment #8)
Created attachment 154067 [details] [review] Bug 34387: (QA follow-up) Fix disply of 'Import batches'
Fixes the heading and sidebar display of the 'Import batches' section.
Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Thanks! -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #10 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154087 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154087&action=edit [23.05.x] Bug 34387: Improve API docs naming consistency This patch aims to make our API docs be more consistent. It addresses two particular things: * There's no consistency on the `tags` used across the spec, and not all of them are correctly described and have an `x-displayName` entry. More on this later. * This are not sorted either by some for of grouping, or at least alphabetically. For the former, I did my best trying to harmonize (specially on the ERM front) with what we do in the rest of the use cases. For the latter, I opted for sorting everything alphabetically, as a first step. Hoping someone else could work on grouping things. To test (ON YOUR HOST MACHINE): 1. On current master run: $ cd api/v1/swagger $ docker run --rm -v $(pwd):/api --workdir /api redocly/cli \ build-docs swagger.yaml --output index.html => SUCCESS: It doesn't break or anything 2. Open your browser, open the generated api/v1/swagger/index.html file => FAIL: The left column has * several lower case entries * not everything is correctly grouped (ERM? packages?) * Things are not sorted. There's an attempt but looks messy 3. Apply this patch 4. Repeat 1 and 2 => SUCCESS: Things look much better! 5. Sign off :-D CAVEAT1: I'm not sure why, but import_batches doesn't work. Ideas are welcome, I'll keep looking for fixes. CAVEAT2: I don't have enough eHoldings background to weight in, but I feel like 'ERM eHoldings packages' could just be 'ERM packages'. Follw-up patches with better ideas are welcome. CAVEAT3: Patron credits, debits, balance... They could all go in to 'Patrons accounts' or similar. Open to ideas. CAVEAT4: Old redocly didn't support mapping an endpoint to more than one target section. Something to explore if we want (for example) to reach 'credits' through the 'Patrons' section but also from 'Accounting'. Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> 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=34387 --- Comment #11 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154088 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154088&action=edit [23.05.x] Bug 34387: (follow-up) Minor spelling and quoting fixes Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> 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=34387 --- Comment #12 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154089 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154089&action=edit [23.05.x] Bug 34387: (QA follow-up) Fix disply of 'Import batches' Fixes the heading and sidebar display of the 'Import batches' section. Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> 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=34387 --- Comment #13 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154090 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154090&action=edit [22.11.x] Bug 34387: Improve API docs naming consistency This patch aims to make our API docs be more consistent. It addresses two particular things: * There's no consistency on the `tags` used across the spec, and not all of them are correctly described and have an `x-displayName` entry. More on this later. * This are not sorted either by some for of grouping, or at least alphabetically. For the former, I did my best trying to harmonize (specially on the ERM front) with what we do in the rest of the use cases. For the latter, I opted for sorting everything alphabetically, as a first step. Hoping someone else could work on grouping things. To test (ON YOUR HOST MACHINE): 1. On current master run: $ cd api/v1/swagger $ docker run --rm -v $(pwd):/api --workdir /api redocly/cli \ build-docs swagger.yaml --output index.html => SUCCESS: It doesn't break or anything 2. Open your browser, open the generated api/v1/swagger/index.html file => FAIL: The left column has * several lower case entries * not everything is correctly grouped (ERM? packages?) * Things are not sorted. There's an attempt but looks messy 3. Apply this patch 4. Repeat 1 and 2 => SUCCESS: Things look much better! 5. Sign off :-D CAVEAT1: I'm not sure why, but import_batches doesn't work. Ideas are welcome, I'll keep looking for fixes. CAVEAT2: I don't have enough eHoldings background to weight in, but I feel like 'ERM eHoldings packages' could just be 'ERM packages'. Follw-up patches with better ideas are welcome. CAVEAT3: Patron credits, debits, balance... They could all go in to 'Patrons accounts' or similar. Open to ideas. CAVEAT4: Old redocly didn't support mapping an endpoint to more than one target section. Something to explore if we want (for example) to reach 'credits' through the 'Patrons' section but also from 'Accounting'. Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> 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=34387 --- Comment #14 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154091 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154091&action=edit [22.11.x] Bug 34387: (follow-up) Minor spelling and quoting fixes Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> 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=34387 --- Comment #15 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154092 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154092&action=edit [22.11.x] Bug 34387: (QA follow-up) Fix disply of 'Import batches' Fixes the heading and sidebar display of the 'Import batches' section. Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> 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=34387 --- Comment #16 from Tomás Cohen Arazi <tomascohen@gmail.com> --- I have attached adapted versions for 23.05 and 22.11. I kept the 3 patches to keep the attribution. -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- QA Contact| |katrin.fischer@bsz-bw.de --- Comment #17 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Thanks Martin and Katrina for testings and the follow-ups. -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|Passed QA |Pushed to master Version(s)| |23.11.00 released in| | -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #18 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Pushed to master for 23.11. Nice work everyone, thanks! -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #19 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154419 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154419&action=edit [23.05.x] Bug 34387: (QA follow-up) Fix display of 'Import batches' Fixes the heading and sidebar display of the 'Import batches' section. Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> 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=34387 --- Comment #20 from Tomás Cohen Arazi <tomascohen@gmail.com> --- Created attachment 154420 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=154420&action=edit [22.11.x] Bug 34387: (QA follow-up) Fix display of 'Import batches' Fixes the heading and sidebar display of the 'Import batches' section. Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de> 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=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #154089|0 |1 is obsolete| | -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #154092|0 |1 is obsolete| | -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Tomás Cohen Arazi <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Keywords|Manual |rel_22_11_candidate, | |rel_23_05_candidate -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #21 from Tomás Cohen Arazi <tomascohen@gmail.com> --- @Rmaints make sure you pick all the patches for your version. I had to amend the last follow-up for an unintended breakage it introduced, and they ended up stacked at the bottom. -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Fridolin Somers <fridolin.somers@biblibre.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |fridolin.somers@biblibre.co | |m Status|Pushed to master |Pushed to stable Version(s)|23.11.00 |23.11.00,23.05.03 released in| | --- Comment #22 from Fridolin Somers <fridolin.somers@biblibre.com> --- Pushed to 23.05.x for 23.05.03 -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 Pedro Amorim <pedro.amorim@ptfs-europe.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Version(s)|23.11.00,23.05.03 |23.11.00,23.05.03,22.11.09 released in| | Status|Pushed to stable |Pushed to oldstable -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34387 --- Comment #23 from Pedro Amorim <pedro.amorim@ptfs-europe.com> --- Nice work everyone! Pushed to 22.11.x for next release -- You are receiving this mail because: You are watching all bug changes.
participants (1)
-
bugzilla-daemon＠bugs.koha-community.org