Closed ProjectZero4 closed 9 months ago
Problem with this and https://github.com/knuckleswtf/scribe/pull/726 is the addition of OAS-specific behaviour and config. Scribe has been focused on the human-readable docs from the start, and I've been loath to add much, especially new configuration items, specific to the OpenAPI spec.
The only way I'd accept this is if the config items are not top-level, and even then...🤔 Actually, come to think about it, can't you achieve this with the openapi.overrides
config?
Ah maybe this is a misunderstanding on my part. I assumed this was meant to be OpenApi First along with Postman. What's the main purpose of this package if not to support these?
The readme says
Scribe helps you generate API documentation for humans
The primary focus is the human-readable HTML docs. Of course, we can improve the OAS and Postman side of things too, but it has to make sense in context.
Ah gotcha, I've not looked at the html generation code yet, does it run off something other than the openapi.yaml file? If I was to make sure these additional fields also added value to the html docs, would that make this make more sense?
does it run off something other than the openapi.yaml file
Yes, there's a whole process that goes on. The openapi spec is just one of three possible outputs, and tbh, it doesn't capture every possibility of Laravel APIs.
I think I'll close this PR. You can achieve this with openapi.overrides
. That's the entire purpose of that config section. Besides, these fields you're proposing are optional fields, things most people don't care about, and they'll just make the config file bigger, impacting usability. Thanks for the effort, but I think it's just as easy to achieve this currently.
…//swagger.io/specification/#info-object
New Config Variables
Before
After