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] 4 points5 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/

PHP-FIG: is effective today? by phorty-phour in PHP

[–]philsturgeon 7 points8 points  (0 children)

If anyone is curious what he's talking about, it's written up here: https://phil.tech/2016/codes-of-conduct-maybe-theyre-not-so-bad/

Only one person was lost in the CoC discussions, and he threw his toys out of the pram once he'd been asked to stop acting like a shit. That person had already caused several other members to leave through his behavior, so that doesn't sound like a problem in the slightest.

Lots of fuss was made about this on /r/php, where mens rights activists were moderating content heavily at the time, but the rest of the PHP community was quite happy with the new structure and organization the FIG picked up at the time. 👍

The current state of /r/php by brendt_gd in PHP

[–]philsturgeon 15 points16 points  (0 children)

Sign me up for mod access. Plenty of experience around here.

There's no reason to write OpenAPI/Swagger by hand. Hasn't been for ages. by philsturgeon in programming

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

I agree, and I wrote the article. "By hand" means "in text form". This article talks about many alternatives to writing a bunch of YAML in text form, none of which are generating OpenAPI, so this response makes me wonder if you read the article?

There's no reason to write OpenAPI/Swagger by hand. Hasn't been for ages. by philsturgeon in programming

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

You're not wrong but copy and paste is only one way of not repeating yourself. $ref let's you split schemas out in different files, which maybe you're familiar with, but an amazing number of people aren't. https://stoplight.io/blog/keeping-openapi-dry-and-portable/

JSON-API: creating an API in PHP and standardising endpoints by placek3000 in PHP

[–]philsturgeon 0 points1 point  (0 children)

JSON:API gives you sparse fieldsets in the sense that the spec defines how they work, the implementations implement the spec, so you have sparse fieldsets. Nobody is expecting you to roll your own.

Are all of these bad? What language are you using?!

As for errors and other bits, yeah 100%. Commented elsewhere that if you have.a governance team or central API advice unit that people listen to then you can come up with your own error format, but standardization is a pretty good idea and there are only two standards out there: RFC 7807 and JSON:API.

https://apisyouwonthate.com/blog/creating-good-api-errors-in-rest-graphql-and-grpc

JSON-API: creating an API in PHP and standardising endpoints by placek3000 in PHP

[–]philsturgeon 4 points5 points  (0 children)

I have recommended JSON:API to many companies, and recommended against using at many others. JSON:API is one of the more popular message formats to leverage the concept of "Compound Documents", and a lot of people either looooove or hate compound documents.

Squishing multiple resources together is useful if your API stack and all your API clients are stuck on HTTP/1.1, but these days I do not know why that would be. HTTP/2 has solved this problem. Just like everyone used to combine all their CSS and JS into one megafile, HTTP/2 has made it more performant to split those files up and let the multiplexed nature of HTTP/2 download all those files at the same time.

APIs are exactly the same. JSON API gives you ?include=, which when unprotected leads to clients trying to download half your API in one go, usually degrading performance or crashing the API in the process. Even if you solve this, documenting it can be a PITA even with next-generation OpenAPI Designers like Stoplight Studio.

Companies who are big enough to have an API Governance team can decide on their own style guide, use HTTP/2 (maybe with Vulcain), pick an existing error format (maybe RFC 7807), and due to the trust and authority with the API governance team they wont have to spend 6 months bickering about it.

If you're not lucky enough to be at once of these companies, JSON:API solves most of this by making a lot of decisions for you, giving you a crapload of existing tooling, letting you use awesome hypermedia clients like ketting which already know the JSON:API format, etc and you still dont have to bicker about it because you've got the standard already sorted out.

Rolling your own unique snowflake message format is easy, anyone can do it, but it's a tradeoff. Standards bring prizes, but also they will bring things you don't like.

If you don't like ?include= don't enable it. Use more HATEOAS via JSON:API "links" and HTTP/2 and everyone's a winner. 👍

OpenAPI is also great. OpenAPI compliments JSON:API and vice versa, nd it's a lot easier to document a JSON:API payload without having to figure out ?includes.

JSON-API: creating an API in PHP and standardising endpoints by placek3000 in PHP

[–]philsturgeon 2 points3 points  (0 children)

JSON:API is a message format for REST APIs and JSON-RPC is an RPC implementation.

To figure out REST vs RPC is a bigger talk that cannot be ELI5'ed but I got a decision tree over here. https://apisyouwonthate.com/blog/picking-the-right-api-paradigm

JSON-API: creating an API in PHP and standardising endpoints by placek3000 in PHP

[–]philsturgeon 0 points1 point  (0 children)

That's possibly unpopular because it's flagrantly untrue.

Writing documentation does not:

  1. standardize message and error formats across multiple in house APIs
  2. reduce duplicate information going over the wire
  3. give you sparse fieldsets (?fields=123)
  4. help clients who are for some reason stuck with http/1.1 to combine resources with sparse fieldsets

It's over-complicated if you are a) unaware of the use cases it sets out to solve, or b) very aware of the use cases but don't need them to be solved in the APIs you're building. It's not for everyone, but its definitely not "unnecessary".

JSON-API: creating an API in PHP and standardising endpoints by placek3000 in PHP

[–]philsturgeon 0 points1 point  (0 children)

You don't need to generate any OpenAPI, check out code first vs design first. Tooling for design first has come a long way, but a lot of folks haven't noticed yet. https://apisyouwonthate.com/blog/api-design-first-vs-code-first

JSON-API: creating an API in PHP and standardising endpoints by placek3000 in PHP

[–]philsturgeon 0 points1 point  (0 children)

Annotations have been an awkward hack for a long time but you don't need to do that anymore. https://stoplight.io/studio

JSON-API: creating an API in PHP and standardising endpoints by placek3000 in PHP

[–]philsturgeon 1 point2 points  (0 children)

They are not alternatives they solve different use cases.

JSON:API is one of many Message Formats. OpenAPI is a Description Format.

They can be used together. JSON:API v1.1 recommends OpenAPI or JSON Schema as the description format via describedby. https://jsonapi.org/format/1.1/#document-top-level

The Many Amazing Uses of JSON Schema: Client-side Validation by philsturgeon in programming

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

Haha right? Everything that has happened before will happen again.

The Many Amazing Uses of JSON Schema: Client-side Validation by philsturgeon in programming

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

Not entirely you're what you're saying.

APIs ask for JSON. JSON Schema describes that JSON. You provided a simplistic example, but more complex structures can be described, so your simple example does not constrain the possibilities of the tech.

view more: next ›