Comments (5)
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.
from openapi-specification.
@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.
from openapi-specification.
@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.
from openapi-specification.
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.
from openapi-specification.
PR that adds the examples in the learn.openapis.org
: OAI/learn.openapis.org#102
I haven't opened a PR yet that cleans-up this repo.
from openapi-specification.
Related Issues (20)
- Behavior of `allowEmptyValue: false` HOT 11
- Open Community (TDC) Meeting, Thursday 16 May 2024 HOT 2
- RFC 7231 has been obsoleted by RFC 9110 HOT 10
- Define a policy using draft PRs when waiting on specific approvals HOT 3
- Open Community (TDC) Meeting, Thursday 23 May 2024 HOT 5
- Open Community (TDC) Meeting, Thursday 30 May 2024 HOT 2
- We should not keep a minified version of respec.js HOT 1
- Document milestone usage in DEVELOPMENT.md
- Define and add new process labels and document general label usage in DEVELOPMENT.md
- Should `style: form` examples include `?` prefix? If so, what about `spaceDelimited`, `pipeDelimited`, and `deepObject`? HOT 4
- Simplify HTML rendering build process HOT 1
- Consolidated $ref-to-Some Object feature request
- Preserve section links in ReSpec output HOT 2
- Open Community (TDC) Meeting, Thursday 06 June 2024 HOT 1
- Add dark mode support to the HTML versions of the OpenAPI specs HOT 3
- Clarify the meaning of info.version HOT 15
- Clarify default dialect for referenced JSON Schema documents HOT 1
- Mention registry in the section defining extensions HOT 3
- Inconsistent or unclear string format : byte or base64 HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from openapi-specification.