Merge pull request #144 from Microsoft/dm/housekeeping

Updates to the Readme along with examples

Author: darrelmiller

README.md

@@ -3,23 +3,87 @@
 # OpenAPI.NET [Preview]
 [ Disclaimer: This repository is in a preview state. Expect to see some iterating as we work towards the final release candidate slated for early 2018. Feedback is welcome! ]
 
-The **OpenAPI.NET** SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OAI JSON and YAML documents from the model.
+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">Open API Initiative</a>**
 
 Project Objectives 
 
-- Provide a single shared object model in .NET for Open API documents.
-- Include the most primitive Reader for ingesting OAI JSON and YAML documents.
-- Enable developers to create Readers that translate different data formats into Open API documents. 
+- Provide a single shared object model in .NET for OpenAPI descriptions.
+- Include the most primitive Reader for ingesting OpenAPI JSON and YAML documents in both V2 and V3 formats.
+- Provide OpenAPI description writers for both V2 and V3 specification formats.
+- Enable developers to create Readers that translate different data formats into OpenAPI descriptions. 
 
 # Readers
-The OpenAPI.NET project holds the base object model for representing OAI documents as .NET objects. Translation for different data types into this object model is handled by reading raw JSON/YAML or from individual "Readers", a number of which are in the works.
+The OpenAPI.NET project holds the base object model for representing OpenAPI descriptions as .NET objects. Translation for different data types into this object model is handled by reading raw JSON/YAML or from individual "Readers", a number of which are in the works.
 
 The base JSON and YAML Readers are built into this project. Below is the list of supported "reader" projects.
 
 - .NET Comment Reader: [Coming Soon]
 
+# Example Usage
+
+Creating an OpenAPI Document
+
+```C#
+var document = new OpenApiDocument
+{
+    Info = new OpenApiInfo
+    {
+        Version = "1.0.0",
+        Title = "Swagger Petstore (Simple)",
+    },
+    Servers = new List<OpenApiServer>
+    {
+        new OpenApiServer { Url = "http://petstore.swagger.io/api" }
+    },
+    Paths = new OpenApiPaths
+    {
+        ["/pets"] = new OpenApiPathItem
+        {
+            Operations = new Dictionary<OperationType, OpenApiOperation>
+            {
+                [OperationType.Get] = new OpenApiOperation
+                {
+                    Description = "Returns all pets from the system that the user has access to",
+                    Responses = new OpenApiResponses
+                    {
+                        ["200"] = new OpenApiResponse
+                        {
+                            Description = "OK"
+                        }
+                    }
+                }
+            }
+        }
+    }
+};
+```
+
+Reading and writing a OpenAPI description
+
+```C#
+var httpClient = new HttpClient
+{
+    BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/")
+};
+
+var stream = await httpClient.GetStreamAsync("master/examples/v3.0/petstore.yaml");
+
+// Read V3 as YAML
+var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostic);
+
+var outputStringWriter = new StringWriter();
+var writer = new OpenApiJsonWriter(outputStringWriter);
+
+// Write V2 as JSON
+openApiDocument.SerializeAsV2(writer);
+
+outputStringWriter.Flush();
+var output = outputStringWriter.GetStringBuilder().ToString();
+
+```
+
 # Build Status
 
 |**master**|
@@ -39,3 +103,5 @@ provided by the bot. You will only need to do this once across all repos using o
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+To provide feedback and ask questions you can use StackOverflow with the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the OpenApi.net Slack channel which you can join by registering for the httpapis team at http://slack.httpapis.com 

build.cmd

@@ -1,10 +1,24 @@
-SET VERSION=0.9.1
+@echo off
+if "%~1"=="" goto :error
+
+SET %VERSION%=%~1
+
+Echo Building Microsoft.OpenApi
+
 SET PROJ=%~dp0src\Microsoft.OpenApi\Microsoft.OpenApi.csproj 
 msbuild %PROJ% /t:restore /p:Configuration=Release
 msbuild %PROJ% /t:build /p:Configuration=Release
 msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts;Version=%VERSION%
 
+Echo Building Microsoft.OpenApi.Readers
+
 SET PROJ=%~dp0src\Microsoft.OpenApi.Readers\Microsoft.OpenApi.Readers.csproj 
 msbuild %PROJ% /t:restore /p:Configuration=Release
 msbuild %PROJ% /t:build /p:Configuration=Release
-msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts;Version=%VERSION%
+msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts;Version=%VERSION%
+
+goto :end
+:error
+echo Version parameter missing e.g. build.cmd 1.0.0-beta0008
+
+:end