First draft of OpenAPI::Linter topic

[manwar]

Hi,

Please review the draft.

Many Thanks.

Best Regards,
Mohammad

[mdperry]

THM (Take Home Message): In my opinion this could be shipped out now, as is; I found the quality of the descriptive text and Perl code to be extremely high.

Things I checked/tested/explored:
I was able to install the module (further details below), and test all of the code examples and files, they all worked perfectly as advertised (in other words I could replicate the output results).
As part of this I used the open-linter command line tool, and was pleased to see when I tried it without any input parameters, it generated a very nice, succinct, informative help message (in contrast to much of my own code).

Full Disclosure: I have never designed a WebAPI in my life, but have through a process of trial and error, figured out how to use the APIs for several biological data portals, and Cloud Computing environments. In other words, I am somewhat out of my depth for this overall topic, and given the title I was unlikely to have read this blog post. However, I learned a ton in the past 24 hours, so I am quite glad I could review it.

I did NOT dissect/critique the body of the Perl Code, but it seemed clean, clear, easy to read/absorb, and as I said it works as advertised (in my hands).

Typos (minor): I think the initial opening riff on The Night Before Christmas needs a closing quotation mark of some type.
Grammatical style: I saw one place where I would have worded it differently, but I believe this is personal preference.

Other Feedback: I think The bit about dependencies is subjective. To whit, in order to get OpenAPI::Linter to install successfully (on my 2024 MacBook Pro running macOS Sonoma v.14.6.1), I had to install a couple of Testing modules that I did not have, and I also had to install (or update?) IO::Socket::SSL which has a requirement for Net::SSLeay. My understanding is that these were needed to resolve this specific error message:
GET https://spec.openapis.org/oas/3.0/schema/2021-09-28: IO::Socket::SSL 2.009+ required for TLS support at /Library/Perl/5.34/JSON/Validator/Store.pm line 190.

So that is NOT part of OpenAPI::Linter, and is more on me. YMMV
Another full disclosure: I found Claude AI (from Anthropic) extremely helpful in diagnosing my "mixed" Perl installation issues.

[briandfoy]

This is a new thread, so I'll just leave this note again. I don't think this module is ready for promotion yet. Here are the issues I've already raised, which I think are systemic issues and have been satisfactorily fixed.

The latest version of the module (0.15) still barfs with runtime code errors on the OpenAPI files. These are problems with code, not the openapi files, since a linter needs to detect and report errors. These problems are severe issues with the structure and concept of code that I have already identified in the repo.

$ openapi-linter --spec basic-swagger.yaml
Not a HASH reference at /home/.../bfoy/perl5/lib/perl5/OpenAPI/Linter.pm line 269.

I can't disclose the files, but these are consumed by very big enterprises without a problem for their tools in Java, Python, and Perl. They all validate against the spec.

I think the likely outcome is that people will try this module and immediately run into these problems on basic OpenAPI spec files in the wild.

[briandfoy]

Previous issue was #554