Skip to content

Create readme for the 3.0 version of the OAS - #1274

Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom
usarid:patch-2
Closed

Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom
usarid:patch-2

Conversation

@usarid

@usaridusarid commented Jul 14, 2017

Copy link
Copy Markdown
Contributor

No description provided.

fehguy
fehguy approved these changes Jul 14, 2017
View reviewed changes

@fehguyfehguy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.

Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in
[Development Guidelines](DEVELOPMENT.md).

@fehguyfehguyJul 14, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?

usarid
usarid commented Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.

@usaridusaridJul 14, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language

@olensmarolensmarJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc

DavidBiesack
DavidBiesack suggested changes Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc

Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc

Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."

(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.

Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.

Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.

Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification,

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.

@DavidBiesackDavidBiesackJul 19, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)

Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.

@DavidBiesackDavidBiesackJul 14, 2017

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board

@usaridusaridJul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.

@olensmar

olensmar commented Jul 18, 2017

Copy link
Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...

@usarid

usarid commented Jul 19, 2017

Copy link
Copy Markdown
ContributorAuthor

Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.

@usarid

usarid commented Jul 24, 2017

Copy link
Copy Markdown
ContributorAuthor

This was eventually implemented in #1281 so let's close this one.

@usaridusarid closed this Jul 24, 2017
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes
+3 more reviewers
@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Create readme for the 3.0 version of the OAS by usarid · Pull Request #1274 · OAI/OpenAPI-Specification · GitHub
Skip to content
Create readme for the 3.0 version of the OAS - #1274
Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Closed
Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Conversation
@usarid
@usaridusarid
commented
Jul 14, 2017

Copy link


Copy Markdown

Contributor
 No description provided. 
fehguy
fehguy
approved these changes
Jul 14, 2017
View reviewed changes
@fehguyfehguy
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.
Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
@fehguyfehguyJul 14, 2017

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?
usarid
usarid
commented
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@usaridusaridJul 14, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language
@olensmarolensmarJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc
DavidBiesack
DavidBiesack
suggested changes
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."
(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.
Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification, 
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
@DavidBiesackDavidBiesackJul 19, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.
@olensmar
olensmar
commented
Jul 18, 2017

Copy link


Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...
@usarid
usarid
commented
Jul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.
@usarid
usarid
commented
Jul 24, 2017

Copy link


Copy Markdown

ContributorAuthor
This was eventually implemented in #1281 so let's close this one.
@usaridusarid
closed this
Jul 24, 2017
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes

+3 more reviewers

@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Create readme for the 3.0 version of the OAS by usarid · Pull Request #1274 · OAI/OpenAPI-Specification · GitHub
Skip to content
Create readme for the 3.0 version of the OAS - #1274
Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Closed
Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Conversation
@usarid
@usaridusarid
commented
Jul 14, 2017

Copy link


Copy Markdown

Contributor
 No description provided. 
fehguy
fehguy
approved these changes
Jul 14, 2017
View reviewed changes
@fehguyfehguy
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.
Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
@fehguyfehguyJul 14, 2017

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?
usarid
usarid
commented
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@usaridusaridJul 14, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language
@olensmarolensmarJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc
DavidBiesack
DavidBiesack
suggested changes
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."
(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.
Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification, 
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
@DavidBiesackDavidBiesackJul 19, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.
@olensmar
olensmar
commented
Jul 18, 2017

Copy link


Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...
@usarid
usarid
commented
Jul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.
@usarid
usarid
commented
Jul 24, 2017

Copy link


Copy Markdown

ContributorAuthor
This was eventually implemented in #1281 so let's close this one.
@usaridusarid
closed this
Jul 24, 2017
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes

+3 more reviewers

@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Create readme for the 3.0 version of the OAS by usarid · Pull Request #1274 · OAI/OpenAPI-Specification · GitHub
Skip to content
Create readme for the 3.0 version of the OAS - #1274
Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Closed
Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Conversation
@usarid
@usaridusarid
commented
Jul 14, 2017

Copy link


Copy Markdown

Contributor
 No description provided. 
fehguy
fehguy
approved these changes
Jul 14, 2017
View reviewed changes
@fehguyfehguy
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.
Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
@fehguyfehguyJul 14, 2017

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?
usarid
usarid
commented
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@usaridusaridJul 14, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language
@olensmarolensmarJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc
DavidBiesack
DavidBiesack
suggested changes
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."
(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.
Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification, 
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
@DavidBiesackDavidBiesackJul 19, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.
@olensmar
olensmar
commented
Jul 18, 2017

Copy link


Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...
@usarid
usarid
commented
Jul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.
@usarid
usarid
commented
Jul 24, 2017

Copy link


Copy Markdown

ContributorAuthor
This was eventually implemented in #1281 so let's close this one.
@usaridusarid
closed this
Jul 24, 2017
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes

+3 more reviewers

@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
Create readme for the 3.0 version of the OAS by usarid · Pull Request #1274 · OAI/OpenAPI-Specification · GitHub
Skip to content
Create readme for the 3.0 version of the OAS - #1274
Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Closed
Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Conversation
@usarid
@usaridusarid
commented
Jul 14, 2017

Copy link


Copy Markdown

Contributor
 No description provided. 
fehguy
fehguy
approved these changes
Jul 14, 2017
View reviewed changes
@fehguyfehguy
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.
Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
@fehguyfehguyJul 14, 2017

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?
usarid
usarid
commented
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@usaridusaridJul 14, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language
@olensmarolensmarJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc
DavidBiesack
DavidBiesack
suggested changes
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."
(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.
Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification, 
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
@DavidBiesackDavidBiesackJul 19, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.
@olensmar
olensmar
commented
Jul 18, 2017

Copy link


Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...
@usarid
usarid
commented
Jul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.
@usarid
usarid
commented
Jul 24, 2017

Copy link


Copy Markdown

ContributorAuthor
This was eventually implemented in #1281 so let's close this one.
@usaridusarid
closed this
Jul 24, 2017
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes

+3 more reviewers

@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Create readme for the 3.0 version of the OAS by usarid · Pull Request #1274 · OAI/OpenAPI-Specification · GitHub
Skip to content
Create readme for the 3.0 version of the OAS - #1274
Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Closed
Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Conversation
@usarid
@usaridusarid
commented
Jul 14, 2017

Copy link


Copy Markdown

Contributor
 No description provided. 
fehguy
fehguy
approved these changes
Jul 14, 2017
View reviewed changes
@fehguyfehguy
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.
Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
@fehguyfehguyJul 14, 2017

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?
usarid
usarid
commented
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@usaridusaridJul 14, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language
@olensmarolensmarJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc
DavidBiesack
DavidBiesack
suggested changes
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."
(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.
Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification, 
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
@DavidBiesackDavidBiesackJul 19, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.
@olensmar
olensmar
commented
Jul 18, 2017

Copy link


Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...
@usarid
usarid
commented
Jul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.
@usarid
usarid
commented
Jul 24, 2017

Copy link


Copy Markdown

ContributorAuthor
This was eventually implemented in #1281 so let's close this one.
@usaridusarid
closed this
Jul 24, 2017
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes

+3 more reviewers

@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Create readme for the 3.0 version of the OAS by usarid · Pull Request #1274 · OAI/OpenAPI-Specification · GitHub
Skip to content
Create readme for the 3.0 version of the OAS - #1274
Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Closed
Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Conversation
@usarid
@usaridusarid
commented
Jul 14, 2017

Copy link


Copy Markdown

Contributor
 No description provided. 
fehguy
fehguy
approved these changes
Jul 14, 2017
View reviewed changes
@fehguyfehguy
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.
Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
@fehguyfehguyJul 14, 2017

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?
usarid
usarid
commented
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@usaridusaridJul 14, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language
@olensmarolensmarJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc
DavidBiesack
DavidBiesack
suggested changes
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."
(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.
Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification, 
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
@DavidBiesackDavidBiesackJul 19, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.
@olensmar
olensmar
commented
Jul 18, 2017

Copy link


Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...
@usarid
usarid
commented
Jul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.
@usarid
usarid
commented
Jul 24, 2017

Copy link


Copy Markdown

ContributorAuthor
This was eventually implemented in #1281 so let's close this one.
@usaridusarid
closed this
Jul 24, 2017
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes

+3 more reviewers

@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
Create readme for the 3.0 version of the OAS by usarid · Pull Request #1274 · OAI/OpenAPI-Specification · GitHub
Skip to content
Create readme for the 3.0 version of the OAS - #1274
Closed
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Closed
Create readme for the 3.0 version of the OAS#1274
usarid wants to merge 1 commit into
OAI:OpenAPI.nextfrom 
usarid:patch-2
Conversation
@usarid
@usaridusarid
commented
Jul 14, 2017

Copy link


Copy Markdown

Contributor
 No description provided. 
fehguy
fehguy
approved these changes
Jul 14, 2017
View reviewed changes
@fehguyfehguy
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great. As noted, we will have to clean up some of the docs we're linking to, but this PR is 👍 from my POV.
Comment threadREADME.md

The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
@fehguyfehguyJul 14, 2017

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's good to leave this, but we will need to update this doc
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a different PR - who can take that?
usarid
usarid
commented
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@usaridusaridJul 14, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs to get updated with TDC language
@olensmarolensmarJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest replacing "OAI Technical Contributors Board" with simply "TDC Contributors" - it's important to note that the OAI or its official members have no direct influence or mandate on the work/direction of the TDC - the suggested wording could be interpreted differently.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the gdoc
DavidBiesack
DavidBiesack
suggested changes
Jul 14, 2017
View reviewed changes
Comment threadREADME.md
The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The current, released version of the OpenAPI Specification is 2.0, through donation of the Swagger Specification to the OAI by SmartBear Software. If you are interested in the release specification, see the [master branch](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md) of this project.
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "The OpenAPI Specification defines ..."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "without access to source code, additional documentation," (the OpenAPI definition is documentation)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
The goal of the OpenAPI Specification is to define a standard, language-agnostic interface description for REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling the service.

Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the OpenAPI Specification, this branch will be merged to master.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: "Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; automated test cases."
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "in this repository" - that is, the document is the spec (the fact that it is in a GigHub repository is unimportant)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc
Comment threadREADME.md
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification documented in this repository. These documents can either be produced and served statically, or be generated dynamically from your application.

The current process for development of the OpenAPI Specification is described in [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md).
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: replace the first sentence with "The OpenAPI Specification design was informed by lessons learned from CORBA, WSDL, WADL, and other historical efforts in defining web services. These other specifications ..."
(I'm not sure one can claim CORBA or WSDL did not gain traction - they did, but were not easy to use. Also, this para seems more related to REST vs other web service architecture, so feels misplaced.)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to omit the paragraph entirely. I don't believe it belongs in the readme of the spec, maybe more in commentary somewhere else.
Comment threadREADME.md

## Current Version - 3.0

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.md).
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

The current version of the OpenAPI specification is 3.0 - and you can find it [here](versions/3.0.md).

### [Previous Versions](versions/2.0.md)
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

defer to the link to 2.0 to the paragraph, not the header.
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
Comment threadREADME.md

### [Previous Versions](versions/2.0.md)

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification, 
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[OpenAPI Specification 2.0](versions/2.0)
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated into the gdoc.
@DavidBiesackDavidBiesackJul 19, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, sorry.... that should be [OpenAPI Specification 2.0](versions/2.0.md) (i.e. the .md extension is required)
Comment threadREADME.md
The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
The current process for development of the OpenAPI Specification is described in 
[Development Guidelines](DEVELOPMENT.md).
Development of the next version of the OpenAPI Specification is guided by the [OAI Technical Contributors Board](CONTRIBUTORS.md). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
@DavidBiesackDavidBiesackJul 14, 2017

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC), not OAI Technical Contributors Board
@usaridusaridJul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, incorporated a slight modification of this in the gdoc.
@olensmar
olensmar
commented
Jul 18, 2017

Copy link


Copy Markdown

@usarid i'd be happy to help make the suggested changes - but your branch doesn't seem to be available...
@usarid
usarid
commented
Jul 19, 2017

Copy link


Copy Markdown

ContributorAuthor
Thanks @olensmar I've been too slammed to look into what happened here, but looking at it now.
@usarid
usarid
commented
Jul 24, 2017

Copy link


Copy Markdown

ContributorAuthor
This was eventually implemented in #1281 so let's close this one.
@usaridusarid
closed this
Jul 24, 2017
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@darrelmillerdarrelmillerdarrelmiller approved these changes

+3 more reviewers

@DavidBiesackDavidBiesackDavidBiesack requested changes
@olensmarolensmarolensmar left review comments
@fehguyfehguyfehguy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

5 participants

@usarid@olensmar@fehguy@darrelmiller@DavidBiesack