Update readme for v3 #1281
Merged
Update readme for v3 #1281
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Incorporated first batch of suggestions from TDC, before any changes from the gdoc.
DavidBiesack
suggested changes
Jul 20, 2017
README.md
Outdated
| The OpenAPI Specification defines 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, additional 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; and automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification. These documents can either be produced and served statically, or be generated dynamically from your application. |
There was a problem hiding this comment.
Still up for debate, but I think we're opting the term "OpenAPI definitions" for the instance docments: "OpenAPI definitions define APIs ...". but that's a bit awkward. "An API is defined by an OpenAPI definition: a YAML or JSON document that adheres to the OpenAPI specification."
README.md
Outdated
| Use cases for machine-readable API interfaces include interactive documentation; code generation for documentation, client, and server; and automated test cases. OpenAPI descriptions describe APIs via YAML or JSON documents that adhere to the OpenAPI Specification. 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). | ||
| The OpenAPI Specification does not require you to rewrite your existing API. It does not require binding any software to a service--the service being described may not even be yours. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI--this specification is not intended to cover every possible use-case of a REST API. The OpenAPI Specification does not define a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API. |
There was a problem hiding this comment.
Change the -- to — (—) in a couple locations. When I view this, the line gets split between the first and second -.
There was a problem hiding this comment.
Also changed "described" to "defined".
| ### Previous Versions | ||
|
|
||
| This repository also contains the [OpenAPI Specification 2.0](versions/2.0), which is identical to the Swagger 2.0 specification, | ||
| as well as the Swagger 1.2 and Swagger 2.0 specifications. |
Member
There was a problem hiding this comment.
Technically it only currently contains one copy of the OpenAPI 2.0 specification, not the Swagger 2.0 specification as well.
README.md
Outdated
|
|
||
| ## Tools and Libraries | ||
|
|
||
| Looking to see how you can create your own OpenAPI definition, present it or otherwise use it? Check out the growing |
README.md
Outdated
| 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 [Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC) and governed by the [TDC Contributors](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. |
There was a problem hiding this comment.
"bring", "incorporate", "expand" should be "brings", "incorporates", "expands" (as in "this group ... brings")
There was a problem hiding this comment.
Can probably drop the process info about "this branch" and merging" as when this becomes the README, this will have been completed and will be in master. I think it is too early to say what the post 3.0.0 process and branch strategy will be. Need more TDC input on this. (I think removing this from the main README is OK - it should be in DEVELOPING.md which is mentioned immediately below)
Work by people in the TDC and marketing committee
README.md
Outdated
| 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 [Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC) and governed by the [TDC Contributors](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. |
Member
There was a problem hiding this comment.
"governed by the [TDC Contributors]" governed seems the wrong word.
usarid
commented
Jul 21, 2017
README.md
Outdated
| 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 [Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC) and governed by the [TDC Contributors](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. |
Contributor
Author
There was a problem hiding this comment.
Per TDC I'll remove the link and discussion of contributors for now.
This was referenced Jul 24, 2017
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Incorporated first batch of suggestions from TDC, before any changes
from the gdoc.