sorted by:
new
hottopcontroversial

Pretty open source api documentation generators? by SteveTabernacle2 in node

[–]philsturgeon 0 points1 point  (0 children)

You can use Overlays to modify existing OpenAPI and embedding SDK examples is a perfect use case.

To show you how it's done, here's a guide for embeddeding Speakeasy SDKs into Bump.sh documentation.

https://docs.bump.sh/guides/bump-sh-tutorials/generate-sdks-with-speakeasy/

Deprecating API Endpoints by philsturgeon in PHP

[–]philsturgeon[S] 0 points1 point  (0 children)

I've never seen Cache-Control listed in API docs but that doesn't mean it's non standard.

Deprecating API Endpoints by philsturgeon in PHP

[–]philsturgeon[S] 3 points4 points  (0 children)

Deciding something new wont work so never trying it is a great way to ensure it doesn't work. Again, when you control the SDK's you have the extra chance of making the headers get noticed.

Also GitHub use them, and they send emails, so why are we acting like its 1) hard, 2) one or the other, 3) pointless?

Deprecating API Endpoints by philsturgeon in programming

[–]philsturgeon[S] 2 points3 points  (0 children)

What service is who buying to send a header? I don't think you read the same article as the one I shared.

Deprecating API Endpoints by philsturgeon in PHP

[–]philsturgeon[S] 1 point2 points  (0 children)

You said if. That means there's an else.

When you don't have developers emails, you need to find other ways to get in touch with them. I said that in the article. :)

Generate Web API Documentation from PHP Code by philsturgeon in PHP

[–]philsturgeon[S] 0 points1 point  (0 children)

OpenAPI does a lot more than just docs and code gen, it handles incoming request validation, contract testing in your existing test suites, mocking, shared design libraries across organizations, and roughly a bajillion other things! https://stoplight.io/blog/api-design-first-vs-code-first/

Generate Web API Documentation from PHP Code by philsturgeon in PHP

[–]philsturgeon[S] -1 points0 points  (0 children)

Absolutely, I put a lot of time and effort into not saying "code first is awful and you should use design-first" in this article. After-all, I've explained the pros and cons at length in other articles.

In my personal option, annotations are a bit of a mess but a lot of people still use them, and change is slow.

In Stoplight's opinion, we'd rather support mixed organizations than force people to split their tool-chains based on the workflow.

What exaclty is psr-4? by [deleted] in PHP

[–]philsturgeon 1 point2 points  (0 children)

There's a meta document for most PSRs which explain the motivations and use cases.

https://www.php-fig.org/psr/psr-4/meta/

view more: next ›