Updates to the Readme along with examples by darrelmiller · Pull Request #144 · microsoft/OpenAPI.NET

darrelmiller · Dec 13, 2017

No description provided.

PerthCharern · Dec 13, 2017

README.md

 The base JSON and YAML Readers are built into this project. Below is the list of supported "reader" projects.

 - .NET Comment Reader: [Coming Soon]
+- OData (CSDL) Reader: [Comming Soon]


I don't see it.

Coming soon with one m.

Now I see it

PerthCharern · Dec 13, 2017

README.md

+The **OpenAPI.NET** SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model.

-**See more information on the Open API spec and its history here: <a href="https://www.openapis.org">Open API Initiative</a>**
+**See more information on the OpenAPI spec and its history here: <a href="https://www.openapis.org">OpenAPI Initiative</a>**


The website for OAI itself has conflicting guideline on how to stylize its own name:

The Open API Initiative refers to the organization that oversees the specification. It must contain ONE space and FIVE capital letters. After the initial declaration, it may be referred to as the “OAI” in subsequent references, ...

Given that the new 3.0.1 spec seems to use OpenAPI (rather than Open API), I am guessing the OAI website itself just needs some updating?

It is OpenAPI for everywhere except for Open API Initiative.

PerthCharern · Dec 13, 2017

README.md

+
+# Example Usage
+
+Creating a OpenAPI Document


PerthCharern · Dec 13, 2017

README.md

+var stream = await httpClient.GetStreamAsync("master/examples/v3.0/petstore.yaml");
+
+// Read V3 as YAML
+var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostics);


Suggest out var diagnostic (without the s) to be consistent with the type name.

PerthCharern · Dec 13, 2017

README.md

+var output = outputStringWriter.GetStringBuilder().ToString();
+
+Assert.Empty(diagnostics.Errors);
+Assert.NotNull(openApiDocument);


I don't think these Asserts are needed in the example.

PerthCharern · Dec 13, 2017

test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs

+            outputStringWriter.Flush();
+            var output = outputStringWriter.GetStringBuilder().ToString();
+
+            Assert.Empty(diagnostics.Errors);


Can we use FluentAssertions here for consistency with the rest of the project?

PerthCharern · Dec 13, 2017

test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs

+
+namespace Microsoft.OpenApi.Readers.Tests.V3Tests
+{
+    public class OpenApiReadmeTests


Do we need this? I'm asking because the second test here means that our unit tests are making out-of-box calls to https://raw.githubusercontent.com/OAI/OpenAPI-Specification/

I am not sure if adding this dependency is a good idea.

Yeah. I can pull it out of the tests. I just needed an example that I could confirm worked.

PerthCharern

🕝

darrelmiller · Dec 13, 2017

@PerthCharern I removed the readme tests until I can redo them based on an embedded resource and using the FluentAssertions.

xuzhg · Dec 13, 2017

README.md

+
+Creating a OpenAPI Document
+
+```Csharp


PerthCharern · Dec 13, 2017

Thanks @darrelmiller. Everything apart from some minor comments above looks okay to me.

PerthCharern · Dec 13, 2017

README.md

 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+To provide feedback and ask questions you can use StackOverflow in the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the Slack OpenApi.net Slack channel which you can register for at http://slack.httpapis.com 


Maybe just "the OpenApi.net Slack channel" instead of "the Slack OpenApi.net Slack channel".

PerthCharern · Dec 13, 2017

README.md

 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+To provide feedback and ask questions you can use StackOverflow in the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the Slack OpenApi.net Slack channel which you can register for at http://slack.httpapis.com 


you can use StackOverflow with the OpenApi.net tag

That sounds a bit more natural to me, but feel free to ignore this if you don't agree.

darrelmiller added 4 commits December 13, 2017 16:35

updates to build.cmd and readme

cb2a248

Added examples

7212aa3

Fixed an OAI reference

5be504b

Merge branch 'master' into dm/housekeeping

48fb81c

PerthCharern reviewed Dec 13, 2017

View reviewed changes

README.md Outdated

# Example Usage

Creating a OpenAPI Document

Copy link

Contributor

PerthCharern Dec 13, 2017

Choose a reason for hiding this comment

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

an

darrelmiller reacted with thumbs up emoji

PerthCharern reviewed Dec 13, 2017

View reviewed changes

PerthCharern suggested changes Dec 13, 2017

View reviewed changes

Removed readme tests

0a63352

xuzhg approved these changes Dec 13, 2017

View reviewed changes

README.md Outdated

Creating a OpenAPI Document

```Csharp

Copy link

Contributor

xuzhg Dec 13, 2017 •

edited

Loading

Choose a reason for hiding this comment

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

" ```C# "

darrelmiller reacted with thumbs up emoji

PerthCharern approved these changes Dec 13, 2017

View reviewed changes

PerthCharern reviewed Dec 13, 2017

View reviewed changes

darrelmiller added 5 commits December 13, 2017 18:15

Fixed issues based on PR reviews

7964975

Added note about slack team

91a8836

Words are hard

393c78c

Merge branch 'master' into dm/housekeeping

6528d86

Removed comment about OData

479e6c7

darrelmiller merged commit 4393e09 into master Dec 14, 2017

darrelmiller deleted the dm/housekeeping branch December 14, 2017 00:10

PerthCharern mentioned this pull request Dec 14, 2017

Examples on how to use the library in README #127

Closed

Search code, repositories, users, issues, pull requests...

Conversation

darrelmiller commented Dec 13, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PerthCharern left a comment

Choose a reason for hiding this comment

Uh oh!

darrelmiller commented Dec 13, 2017

Uh oh!

xuzhg Dec 13, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PerthCharern commented Dec 13, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

xuzhg Dec 13, 2017 •

edited

Loading