search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.82k stars 9.07k forks source link

Move examples to learn.openapis.org or spec.openapis.org #3854

Closed handrews closed 4 weeks ago

handrews commented 3 months ago

Can we move the examples in this repo (that are not part of the spec) either to the learn site or to the spec site (run from gh-pages, but see #3717 for how that is likely to change).

Going through all of the open issues just now (again), it's confusing to sort out the issues on examples in the spec from the issues about the examples directory from the general examples issues that we all agree should go on the learn site. It would really help with issue curating if all of the outside-of-spec examples lived in one place.

handrews commented 3 months ago

One concern would be that published specs link to the examples. We could either treat this like past broken links - OK to fix in place because doing so preserves the original text and behavior, rather than achanging it. Or we could do something involving redirects, atlhough whether that's feasible in GitHub I do not know.

I would prefer to move all official links to a hosted site and not be dependent on GitHub because stapling our development environment to our publication channel means we can't organize development in the idea way.

miqui commented 3 months ago

@handrews if by "spec example" you mean this: https://spec.openapis.org/oas/latest.html#examples, then I would simply leave this area as is. IMHO, good to have simple example within the spec itself immediately after the concept in question (rather than having to switch to another site, location).

If you mean "non-spec" example from these: https://github.com/OAI/OpenAPI-Specification/tree/main/examples then my humble vote is to move these to the learn site.

(on a personal note, I have never used these examples, but used the examples in the spec as I was trying to learn the spec itself and then googled, searched in github, searched in POSTMAN, etc for more complicated examples of OADs.

handrews commented 3 months ago

@miqui yes, your interpretation is correct - spec examples stay in the spec, but the non-spec (which you correctly identified) are the ones I'm suggesting we move. I have also added a link to the Learn site at the top of the spec on @lornajane 's suggestion:

That will make it easier for folks who, like you, look for examples in the spec, to find the examples we have elsewhere. And it's easiest if we can just send them to the Learn site instead of multiple locations.

darrelmiller commented 3 months ago

In TDC meeting, there were no objections to moving examples over to the learn site. This will require moving the convert to json action over also.

The spec references to examples will need to be moved to point to the learn site.

Bellangelo commented 3 months ago

PR that adds the examples in the learn.openapis.org: https://github.com/OAI/learn.openapis.org/pull/102 I haven't opened a PR yet that cleans-up this repo.