Yeah, I hate that. I keep getting files that have a ".docx" extension and I have no idea what to do with them. And the designers are using some program that uses ".ps". Thanks guys.
Not sure if you try to be sarcastic or not. But yeah I expect people to chop up their PS files before they send them to me. docx at least has has free viewers. A PDF or HTML would be better.
Paw can do a reasonably good job of exporting an OpenAPI (Swagger) 2.0 description of the API, but the usefulness of the export will depend on the extent to which the Paw-user "dressed up" the request objects.
OpenAPI / Swagger is just JSON which describes the input and output data from an API's endpoints. If you want to know, prior to runtime (of your code), what kind of data an API will accept and return, and if you don't have access to the API's source code, in what would format would you prefer to have the information documented? I don't have in mind a right or wrong answer, just curious.
Well everything was defined as String even when it was expecting an Int or Bool value. But sometimes an Int still needed to be wrapped in double quotes to work. No date formats. Objects returned of type class A sometimes had only 30% of it's fields populated (like after an insert only the database ID and creation date). Fields expecting an enum like value but the expected values not specified.
I mean it makes sense if you just export some kind of Postman / Paw configuration without paying any attention to it. File > Export > Bye Bye.
Of course most of my complaints are related to a lazy programmer sending "documentation" with the absolute least amount of effort possible, but I now at least understand how it was made and why it was as awful as it was.
Indeed, it sounds like there was a bit of a problem "between keyboard and chair" when it came to the Postman / Paw user with whom you interacted.
I had good success, just recently, using Paw to knock out the broad strokes an OpenAPI description, including indications of integer, string, boolean, date, etc. After I got the hang of thinking in terms of OpenAPI, I converted the JSON to YAML and started fine-tuning and DRY'ing the description in Emacs.
I would still use Paw as an exploratory tool — it's not perfect, but I find it more convenient than maintaining a collection of scripts and snippets to experiment with API input/output. Next time I need to write an OpenAPI description, though, if I can't auto-generate it from the server code (that was the case recently), I'll just author it by hand. It's not too big of a chore when done in YAML format, with the help of "feedback loops" per ReDoc[1] and Swagger Editor[2].
