Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

* Scribe now natively supports all info fields described here https:… #729

Conversation

ProjectZero4
Copy link
Contributor

@ProjectZero4 ProjectZero4 commented Sep 14, 2023

…//swagger.io/specification/#info-object

New Config Variables
image

Before
image

After
image

@shalvah
Copy link
Contributor

shalvah commented Sep 14, 2023

Problem with this and #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?

@ProjectZero4
Copy link
Contributor Author

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?

@shalvah
Copy link
Contributor

shalvah commented Sep 14, 2023

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.

@ProjectZero4
Copy link
Contributor Author

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?

@shalvah
Copy link
Contributor

shalvah commented Sep 14, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants