forked from Azure/autorest
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathparams.json
6 lines (6 loc) · 6.37 KB
/
params.json
1
2
3
4
5
6
{
"name": "Autorest",
"tagline": "Swagger (OpenAPI) Specification code generator for C#, Ruby, Python, Node, Java, Go...",
"body": "[](https://travis-ci.org/Azure/autorest) [](http://issuestats.com/github/Azure/autorest) [](http://issuestats.com/github/Azure/autorest)\r\n\r\n# <img align=\"center\" src=\"https://raw.githubusercontent.com/Azure/autorest/master/Documentation/images/autorest-small-flat.png\"> AutoRest\r\n\r\nThe **AutoRest** tool generates client libraries for accessing RESTful web services. Input to *AutoRest* is a spec that describes the REST API using the [Open API Initiative](https://github.com/OAI/OpenAPI-Specification) format.\r\n\r\n##Getting AutoRest\r\nThe AutoRest tools can be installed with Nuget for use in a Visual Studio project:\r\n[](https://www.nuget.org/packages/autorest/)\r\n\r\nAlternatively it can be installed from [Chocolatey](https://chocolatey.org/) by running:\r\n[](https://chocolatey.org/packages/AutoRest)\r\n\r\n choco install autorest\r\n \r\nNightlies are available via MyGet:\r\n[](https://www.myget.org/gallery/autorest)\r\n\r\nAutoRest can be run on OSX and Unix using Mono or by running Docker container:\r\n\t\r\n\tdocker pull azuresdk/autorest:latest\r\n\r\n## Building AutoRest\r\nAutoRest is developed primarily in C# but generates code for multiple languages. See [this link](docs/developer/guide/building-code.md) to build and test AutoRest.\r\n\r\n> Hint: There is a powershell script (`verify-settings.ps1`) in the `Tools` folder that can verify that you have the required compilers/tools/libraries installed on your development system before trying to build.\r\n\r\n## Hello World\r\nFor this version of Hello World, we will use **AutoRest** to generate a client library and use it to call a web service. The trivial web service that just returns a string is defined as follows:\r\n```C#\r\npublic class HelloWorldController : ApiController\r\n{\r\n // GET: api/HelloWorld\r\n public string Get()\r\n {\r\n return \"Hello via AutoRest.\";\r\n }\r\n}\r\n```\r\nBy convention, Swagger documents are exposed by web services with the name `swagger.json`. The `title` property of the `info` object is used by **AutoRest** as the name of the client object in the generated library. The `host` + `path` of the operation corresponds to the URL of the operation endpoint. The `operationId` is used as the method name. The spec declares that a `GET` request will return an HTTP 200 status code with content of mime-type `application/json` and the body will be a string. For a more in-depth overview of swagger processing, refer to [Defining Clients With Swagger](docs/developer/guide/defining-clients-swagger.md) section of the [documentation](docs).\r\n\r\n```json\r\n{\r\n \"swagger\": \"2.0\",\r\n \"info\": {\r\n \"title\": \"MyClient\",\r\n \"version\": \"1.0.0\"\r\n },\r\n \"host\": \"swaggersample.azurewebsites.net\",\r\n \"paths\": {\r\n \"/api/HelloWorld\": {\r\n \"get\": {\r\n \"operationId\": \"GetGreeting\",\r\n \"produces\": [\r\n \"application/json\"\r\n ],\r\n \"responses\": {\r\n \"200\": {\r\n \"description\": \"GETs a greeting.\",\r\n \"schema\": {\r\n \"type\": \"string\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n```\r\nNext, we invoke **AutoRest.exe** with this swagger document to generate client library code (see [Command Line Interface documentation](docs/user/cli.md) for details).\r\n\r\n**AutoRest** is extensible and can support multiple types of input and output. *AutoRest.exe* comes with the *AutoRest.json* configuration file that defines the available inputs (*Modelers*) and outputs (*CodeGenerators*). When invoking *AutoRest.exe*, if you don't specify the `-Modeler` then Swagger is assumed and if you don't specify `-CodeGenerator` then CSharp is used.\r\n\r\nThe Swagger schema is language agnostic and doesn't include the notion of namespace, but for generating code, AutoRest requires `-Namespace` be specified. By default, the CodeGenerator will place output in a directory named *Generated*. This can be overridden by providing the `-OutputDirectory` parameter.\r\n\r\n```\r\nAutoRest.exe -CodeGenerator CSharp -Modeler Swagger -Input swagger.json -Namespace MyNamespace\r\n```\r\n\r\nNow, we will use the generated code to call the web service.\r\n\r\nCreate a console application called *HelloWorld*. Add the generated files to it. They won't compile until you add the NuGet package the generated code depends on: `Microsoft.Rest.ClientRuntime`.\r\n\r\nYou can add it to the Visual Studio project using the NuGet package manager or in the Package Manager Console with this command:\r\n```PowerShell\r\nInstall-Package Microsoft.Rest.ClientRuntime\r\n```\r\n\r\nAdd the namespace that was given to AutoRest.\r\n```C#\r\nusing MyNamespace;\r\n```\r\nAccess the REST API with very little code (see [Client Initialization](docs/client/init.md) and [Client Operations](docs/client/ops.md) for details).\r\n```C#\r\nvar myClient = new MyClient();\r\nvar salutation = myClient.GetGreeting();\r\nConsole.WriteLine(salutation);\r\n```\r\nRunning the console app shows the greeting retrieved from the service API.\r\n```bat\r\nC:\\>HelloWorld.exe\r\nHello via AutoRest.\r\n```\r\n\r\nWith that same basic pattern in place, you can now explore how different REST API operations and payloads are described in Swagger and exposed in the code generated by **AutoRest**.\r\n\r\n---\r\nThis 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.\r\n",
"note": "Don't delete this file! It's used internally to help with page regeneration."
}