зеркало из https://github.com/Azure/autorest.git
Merge pull request #3709 from Azure/new_docs
This commit is contained in:
iscai-msft
GitHub
Коммит
8c68bc4689
42
building.md
42
building.md
|
|
@ -1,42 +0,0 @@
|
|||
# Building AutoRest
|
||||
|
||||
## Cloning this repository
|
||||
Clone the repository
|
||||
|
||||
> `git clone https://github.com/Azure/autorest`
|
||||
|
||||
It is *not* necessary to clone recursively (`--recurse`) - that is only needed for advanced scenarios.
|
||||
|
||||
## Prerequisites
|
||||
Install [Node.js](https://nodejs.org/en/) (10.16.x LTS HIGHLY RECOMENDED)
|
||||
> for more help, check out [Installing Node.JS on different platforms](./docs/developer/workstation.md#nodejs)
|
||||
|
||||
Install [Rush](https://rushjs.io/pages/intro/welcome/) to manage the build process:
|
||||
> `npm install -g "@microsoft/rush" `
|
||||
|
||||
|
||||
## Preparation
|
||||
The first time (or after pulling from upstream) use `rush` to install dependencies
|
||||
> `rush update`
|
||||
|
||||
## Compiling AutoRest
|
||||
Use `rush` to build packages
|
||||
> `rush rebuild`
|
||||
|
||||
|
||||
## Other `rush` commands
|
||||
|
||||
### Cleaning output folder
|
||||
> `rush clean`
|
||||
|
||||
### Running test scripts
|
||||
> `rush test` -- runs the unit tests.
|
||||
|
||||
### Ensuring that packge versions are synchronized across projects
|
||||
|
||||
> `rush sync-versions` -- will make sure that dependent packages versions are consistent across sub-projects
|
||||
|
||||
### Using watch mode to compile on save
|
||||
|
||||
> `rush watch` -- will watch for changes on disk and recompile.
|
||||
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
# Authentication
|
||||
By default, AutoRest generates clients that make unauthenticated HTTP requests. When the [--add-credentials](../user/command-line-interface.md) flag is set to `true`, the generated client will include a `Credentials` property of type [ServiceClientCredentials](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/ServiceClientCredentials.cs). The Microsoft.Rest.ClientRuntime package includes at least the following `ServiceClientCredentials` :
|
||||
|
||||
* [`TokenCredentials`](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/TokenCredentials.cs) - used for OAuth authentication.
|
||||
* [`BasicAuthenticationCredentials`](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/BasicAuthenticationCredentials.cs) - used for basic username/password authentication.
|
||||
* [`CertificateCredentials`](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/CertificateCredentials.cs)
|
||||
|
||||
Custom authentication behaviors can be implemented by inheriting from [ServiceClientCredentials](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/CertificateCredentials.cs). The `ProcessHttpRequestAsync()` method is invoked for each HTTP request.
|
||||
|
||||
## Authenticating with Azure
|
||||
In addition to using [`TokenCredentials`](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/TokenCredentials.cs) with raw OAuth token, a [Microsoft.Rest.ClientRuntime.Azure.Authentication](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Azure.Authentication/2.0.0-preview) nuget package can be used.
|
||||
|
||||
`Microsoft.Rest.ClientRuntime.Azure.Authentication` supports both username/password and service principal login scenarios.
|
||||
|
||||
**Login using service principal and certificate**
|
||||
|
||||
```csharp
|
||||
using Microsoft.Rest.Azure.Authentication;
|
||||
...
|
||||
|
||||
X509Certificate2Collection certificate = <load cert>;
|
||||
byte[] certificateAsBytes = certificate.Export(X509ContentType.Pkcs12, _certificatePassword);
|
||||
ServiceClientCredentials creds = await ApplicationTokenProvider.LoginSilentAsync("<mydomain>", "<client_id>", certificateAsBytes, _certificatePassword);
|
||||
```
|
||||
|
||||
**Login using username and password**
|
||||
|
||||
```csharp
|
||||
using Microsoft.Rest.Azure.Authentication;
|
||||
...
|
||||
|
||||
ServiceClientCredentials creds = await UserTokenProvider.LoginSilentAsync("<client_id>", "<domain>", "<username>", "<password>");
|
||||
```
|
||||
|
||||
**Login with a prompt**
|
||||
|
||||
```csharp
|
||||
using Microsoft.Rest.Azure.Authentication;
|
||||
...
|
||||
|
||||
ServiceClientCredentials creds = await UserTokenProvider.LoginWithPromptAsync("<domain>", ActiveDirectoryClientSettings.UsePromptOnly("<client_id>", new Uri("urn:ietf:wg:oauth:2.0:oob")));
|
||||
```
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
# Error Handling
|
||||
When errors are encountered while executing client operations, they are surfaced with an `HttpOperationException`. The exception includes the HTTP Request and Response objects as shown in this example:
|
||||
```csharp
|
||||
try
|
||||
{
|
||||
pets = client.FindPets(null, -1);
|
||||
}
|
||||
catch (HttpOperationException ex)
|
||||
{
|
||||
var request = ex.Request;
|
||||
var response = ex.Response;
|
||||
}
|
||||
```
|
||||
Many services define models for error conditions. Use either the base type `RestException` or a model type to catch the exception:
|
||||
```csharp
|
||||
try
|
||||
{
|
||||
pets = client.FindPets(null, -1);
|
||||
}
|
||||
catch (RestException ex)
|
||||
{
|
||||
var request = ex.Request;
|
||||
var response = ex.Response;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
pets = client.FindPets(null, -1);
|
||||
}
|
||||
catch (PetException ex)
|
||||
{
|
||||
var request = ex.Request;
|
||||
var response = ex.Response;
|
||||
var errorData = ex.Body;
|
||||
var message = errorData.Message;
|
||||
}
|
||||
```
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
# Initialization
|
||||
AutoRest generates a client type based on command-line inputs and the specification (see [Defining Clients with Swagger](../developer/guide/how-autorest-generates-code-from-swagger.md). The generated client inherits from the [ServiceClient<T>](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/ServiceClient.cs) base type which is in the *Microsoft.Rest.ClientRuntime* nuget package.
|
||||
|
||||
The client type has several constructors:
|
||||
## Default Constructor
|
||||
The default constructor sets the Base URL of the client to the value provided in the specification. The client is configured to use anonymous authentication.
|
||||
```csharp
|
||||
var myClient = new SwaggerPetstore();
|
||||
```
|
||||
## Constructor with Base URL
|
||||
The default Base URL from the specification can be overridden by passing a new URL when instantiating the client.
|
||||
```csharp
|
||||
var myClient = new SwaggerPetstore(new Uri("https://contoso.org/myclient"));
|
||||
```
|
||||
## Constructor with Credentials
|
||||
* Clients generated with the AddCredentials flag have a *Credentials* property and a constructor that accepts a Credentials object (see [Authentication](auth.md))
|
||||
```csharp
|
||||
var myClient = new SwaggerPetstore(new BasicAuthenticationCredentials
|
||||
{
|
||||
UserName = "ContosoUser",
|
||||
Password = "P@$$w0rd"
|
||||
});
|
||||
```
|
||||
## Constructor with Delegating Handlers
|
||||
The generated client includes a constructor that includes all the optional parameters from above and a collection of delegating handlers
|
||||
```csharp
|
||||
var myClient = new SwaggerPetstore(new MyCustomDelegatingHandler());
|
||||
```
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# Client Operations
|
||||
|
||||
## Calling operations
|
||||
AutoRest provides both synchronous and asynchronous method overloads for each service operation. Use the following syntax to call the synchronous method:
|
||||
```csharp
|
||||
var pets = client.FindPets(null, 10);
|
||||
```
|
||||
Use the following syntax to call the asynchronous method:
|
||||
```csharp
|
||||
var petsTask = client.FindPetsAsync(null, 10);
|
||||
|
||||
...
|
||||
|
||||
if (petsTask.Wait(TimeSpan.FromSeconds(10)))
|
||||
{
|
||||
pets = petsTask.Result;
|
||||
}
|
||||
```
|
||||
|
||||
## Getting HTTP request and response information
|
||||
To access HTTP request and response information for a service operation, use the following method:
|
||||
```csharp
|
||||
var petsResult = client.FindPetsWithOperationResponseAsync(null, 10, CancellationToken.None).Result;
|
||||
```
|
||||
To access the HTTP request:
|
||||
```csharp
|
||||
var request = petsResult.Request;
|
||||
```
|
||||
To access the HTTP response:
|
||||
```csharp
|
||||
var response = petsResult.Response;
|
||||
```
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# Project Setup
|
||||
The C# code generated by C# can be included in multiple Visual Studio project types:
|
||||
|
||||
* Desktop applications (.NET 4.0 and .NET 4.5)
|
||||
* Web applications (.NET 4.0 and .NET 4.5)
|
||||
* Windows Phone (8.1)
|
||||
* Windows Store App (8.1)
|
||||
* Portable Class Libraries
|
||||
|
||||
### Add Generated Files to the Project
|
||||
After generating code into an existing project directory, open the Solution Explorer tab in Visual Studio and click the "Show All Files" button to make the files that are not part of the project visible.
|
||||
|
||||
|
||||
Right-click on the `Generated` folder and select `Include In Project` from the context menu.
|
||||
|
||||
|
||||
### Add the ClientRuntime NuGet Package
|
||||
AutoRest generates code that depends on the *Microsoft.Rest.ClientRuntime* NuGet package. This package includes a dependency on *Newtonsoft.Json.Net*. Depending on your project profile, NuGet may pull down several additional packages dependencies.
|
||||
|
||||
Use the Package Manager UI to add *Microsoft.Rest.ClientRuntime*.
|
||||
|
||||
|
||||
Or install using the Package Manager Console.
|
||||
```bash
|
||||
PM>Install-Package Microsoft.Rest.ClientRuntime
|
||||
```
|
||||
|
||||
### Use the Client:
|
||||
```csharp
|
||||
var client = new SwaggerPetstore();
|
||||
Pet myPet = client.FindPetById(10);
|
||||
```
|
||||
|
|
@ -1,8 +1,13 @@
|
|||
# Client Apps
|
||||
- [Project Setup](proj-setup.md)
|
||||
- [Initialization](init.md)
|
||||
- [Authentication](auth.md)
|
||||
- [Client Operations](ops.md)
|
||||
- [Error Handling](error.md)
|
||||
- [Automatic Retries](retry.md)
|
||||
- [Tracing](tracing.md)
|
||||
# <img align="center" src="../images/logo.png"> Using the Generated Client
|
||||
|
||||
This is highly-language specific, so please refer to the documentation we have for our individual language generators:
|
||||
- [Python][python]
|
||||
- [Java][java]
|
||||
- [C#][csharp]
|
||||
- [Typescript][typescript]
|
||||
|
||||
<!--LINKS-->
|
||||
[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/client
|
||||
[java]: https://github.com/Azure/autorest.java/tree/v4/docs/client
|
||||
[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/client
|
||||
[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/client
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
# Automatic Retries
|
||||
AutoRest generated clients support a number of retry policies based on [The Transient Fault Handling Application Block](https://msdn.microsoft.com/en-us/library/hh680934%28v=pandp.50%29.aspx). Retry policies allow generated clients to automatically recover from transient server errors (e.g. error code 5XX).
|
||||
|
||||
There are two ways to customize the retry behavior:
|
||||
|
||||
- Change the detection strategy - define which server error responses need to be retried and which ones should to be re-thrown
|
||||
- Change the retry strategy - specify how long and how many times to continue retrying
|
||||
|
||||
By default, the detection strategy is configured to retry on HttpStatusCode 408 (RequestTimeout) as well as all 5XX codes. The only exceptions are 501 (NotImplemented) and 505 (HttpVersionNotSupported) status codes which are re-thrown to the user.
|
||||
|
||||
The default retry strategy is based on exponential back-off with maximum of three attempts, back-off delta of 10 seconds, minimum back-off of 1 second, and maximum back-off of 10 seconds.
|
||||
|
||||
## Changing the Detection Strategy
|
||||
Detection strategy can be customized by implementing interface [ITransientErrorDetectionStrategy](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/TransientFaultHandling/ITransientErrorDetectionStrategy.cs):
|
||||
```csharp
|
||||
public class ServerErrorDetectionStrategy : ITransientErrorDetectionStrategy
|
||||
{
|
||||
public bool IsTransient(Exception ex)
|
||||
{
|
||||
if (ex != null)
|
||||
{
|
||||
// AutoRest will use this error type for all server errors.
|
||||
HttpRequestWithStatusException httpException;
|
||||
if ((httpException = ex as HttpRequestWithStatusException) != null)
|
||||
{
|
||||
// Condition to retry
|
||||
if (httpException.StatusCode == HttpStatusCode.InternalServerError)
|
||||
{
|
||||
return true;
|
||||
}
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
}
|
||||
```
|
||||
Finally, set the client retry policy using preferred retry strategy:
|
||||
```csharp
|
||||
var retryPolicy = new RetryPolicy<ServerErrorDetectionStrategy>(new FixedIntervalRetryStrategy());
|
||||
client.SetRetryPolicy(retryPolicy);
|
||||
```
|
||||
|
||||
## Changing the Retry Strategy
|
||||
Microsoft.Rest.ClientRuntime comes with three built-in retry strategies:
|
||||
|
||||
- [ExponentialBackoffRetryStrategy](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/TransientFaultHandling/ExponentialBackoffRetryStrategy.cs) - a retry strategy with backoff parameters for calculating the exponential delay between retries
|
||||
- [FixedIntervalRetryStrategy](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/TransientFaultHandling/FixedIntervalRetryStrategy.cs) - a retry strategy with a specified number of retry attempts and a default, fixed time interval between retries
|
||||
- [IncrementalRetryStrategy](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/TransientFaultHandling/IncrementalRetryStrategy.cs) - a retry strategy with a specified number of retry attempts and an incremental time interval between retries
|
||||
|
||||
In order to set the retry strategy in the client, follow these steps:
|
||||
```csharp
|
||||
var retryPolicy = new RetryPolicy<HttpStatusCodeErrorDetectionStrategy>(new FixedIntervalRetryStrategy(10));
|
||||
client.SetRetryPolicy(retryPolicy);
|
||||
```
|
||||
|
||||
In order to implement a custom retry strategy extend [RetryStrategy](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/TransientFaultHandling/RetryPolicy.cs) abstract class.
|
||||
|
|
@ -1,80 +0,0 @@
|
|||
# Tracing
|
||||
Clients generated with AutoRest come with an extensible tracing infrastructure. The following events are traced when the client is executed:
|
||||
|
||||
- EnterMethod - operation method is entered
|
||||
- SendRequest - Http request is sent
|
||||
- ReceiveResponse - Http response is received
|
||||
- TraceError - error is raised
|
||||
- ExitMethod - method is exited
|
||||
|
||||
## Tracing with ETW
|
||||
In order to enable ETW tracing first download _Microsoft.Rest.ClientRuntime.Etw_ package from NuGet.
|
||||
Next, register `EtwTracingInterceptor` by calling:
|
||||
```csharp
|
||||
ServiceClientTracing.AddTracingInterceptor(new EtwTracingInterceptor());
|
||||
ServiceClientTracing.IsEnabled = true;
|
||||
```
|
||||
Finally, use a tool such as [PerfView](http://www.microsoft.com/en-us/download/details.aspx?id=28567) to capture events under the `Microsoft.Rest` provider.
|
||||
|
||||
## Tracing with Log4Net
|
||||
In order to enable Log4Net tracing first download _Microsoft.Rest.ClientRuntime.Log4Net_ package from NuGet. Then, configure the Log4Net in your app.config/web.config (or your preferred way). For more examples on the available configurations check [config examples](http://logging.apache.org/log4net/release/config-examples.html)
|
||||
|
||||
Here's an example of app.config for the logger used with ConsoleAppender:
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
<configuration>
|
||||
<configSections>
|
||||
<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net"/>
|
||||
</configSections>
|
||||
<log4net>
|
||||
<appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
|
||||
<layout type="log4net.Layout.SimpleLayout" />
|
||||
</appender>
|
||||
<root>
|
||||
<level value="ALL" />
|
||||
<appender-ref ref="ConsoleAppender" />
|
||||
</root>
|
||||
<logger name="Microsoft.Rest.Tracing.Log4Net.Log4NetTracingInterceptor">
|
||||
<level value="DEBUG" />
|
||||
<appender-ref ref="ConsoleAppender"/>
|
||||
</logger>
|
||||
</log4net>
|
||||
</configuration>
|
||||
```
|
||||
Next, configure Log4Net in the application by adding this line to `AssemblyInfo.cs` of the application:
|
||||
```csharp
|
||||
[assembly: log4net.Config.XmlConfigurator(Watch = true, ConfigFile = "FileName.ext")]
|
||||
```
|
||||
Finally, register `Log4NetTracingInterceptor` by calling:
|
||||
```csharp
|
||||
ServiceClientTracing.AddTracingInterceptor(new Log4NetTracingInterceptor());
|
||||
ServiceClientTracing.IsEnabled = true;
|
||||
```
|
||||
|
||||
## Custom Tracing
|
||||
In order to trace AutoRest generated client implement a custom type that extends [IServiceClientTracingInterceptor](https://github.com/Azure/azure-sdk-for-net/blob/psSdkJson6/src/SdkCommon/ClientRuntime/ClientRuntime/IServiceClientTracingInterceptor.cs).
|
||||
```csharp
|
||||
using Microsoft.Rest;
|
||||
...
|
||||
|
||||
public class ConsoleTracingInterceptor : IServiceClientTracingInterceptor
|
||||
{
|
||||
public void Information(string message)
|
||||
{
|
||||
Console.WriteLine(message);
|
||||
}
|
||||
|
||||
public void SendRequest(string invocationId, HttpRequestMessage request)
|
||||
{
|
||||
string requestAsString = request == null ? string.Empty : request.AsFormattedString();
|
||||
Console.WriteLine(requestAsString);
|
||||
}
|
||||
|
||||
...
|
||||
}
|
||||
```
|
||||
Finally, register the custom tracing interceptor by calling:
|
||||
```csharp
|
||||
ServiceClientTracing.AddTracingInterceptor(new ConsoleTracingInterceptor());
|
||||
ServiceClientTracing.IsEnabled = true;
|
||||
```
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
# <img align="center" src="../images/logo.png"> Developing and Contributing to AutoRest
|
||||
|
||||
Current docs are [here][writing_an_extension], more incoming
|
||||
|
||||
<!-- LINKS -->
|
||||
[writing_an_extension]: writing-an-extension.md
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
# <img align="center" src="/docs/images/logo.png"> Sample : Generating a client using AutoRest
|
||||
|
||||
First, download the petstore.yaml example file:
|
||||
|
||||
| Platform | Command |
|
||||
|----|---|
|
||||
|PowerShell|`iwr https://raw.githubusercontent.com/Azure/autorest/master/Samples/openapi-v2/1b-code-generation-multilang/petstore.yaml -o petstore.yaml`|
|
||||
|Linux/OS X|`curl -O https://raw.githubusercontent.com/Azure/autorest/master/Samples/openapi-v2/1b-code-generation-multilang/petstore.yaml`|
|
||||
|
||||
Next, generate the client:
|
||||
|
||||
``` powershell
|
||||
# generate the client
|
||||
> autorest --input-file=petstore.yaml --csharp --output-folder=CSharp_PetStore --namespace=PetStore
|
||||
The Microsoft.Rest.ClientRuntime.2.2.0 nuget package is required to compile the generated code.
|
||||
|
||||
# show what got generated:
|
||||
> ls CSharp_PetStore -r
|
||||
|
||||
Directory: ...\CSharp_PetStore
|
||||
|
||||
Mode LastWriteTime Length Name
|
||||
---- ------------- ------ ----
|
||||
d----- 2/24/2017 12:20 PM Models
|
||||
-a---- 2/24/2017 12:20 PM 17657 ISwaggerPetstore.cs
|
||||
-a---- 2/24/2017 12:20 PM 133979 SwaggerPetstore.cs
|
||||
-a---- 2/24/2017 12:20 PM 36933 SwaggerPetstoreExtensions.cs
|
||||
|
||||
Directory: ...\CSharp_PetStore\Models
|
||||
|
||||
Mode LastWriteTime Length Name
|
||||
---- ------------- ------ ----
|
||||
-a---- 2/24/2017 12:20 PM 2454 Category.cs
|
||||
-a---- 2/24/2017 12:20 PM 5214 Order.cs
|
||||
-a---- 2/24/2017 12:20 PM 6610 Pet.cs
|
||||
-a---- 2/24/2017 12:20 PM 2409 Tag.cs
|
||||
-a---- 2/24/2017 12:20 PM 6305 User.cs
|
||||
-a---- 2/24/2017 12:20 PM 4026 XmlSerialization.cs
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,281 @@
|
|||
# <img align="center" src="../images/logo.png"> Directives
|
||||
|
||||
Directives are used to tweak the generated code prior to generation, and are included in your configuration file (usually a README file). For example, if you want to change a property's name from the name defined in the OpenAPI definition, you can add a directive in your readme to accomplish this.
|
||||
|
||||
We usually recommend changing the swagger before going the directive route, but if you'd like the original swagger to remain untouched (for example, you want to rename the generated model in the Python SDK, but not in other SDKs), directives are the route for you.
|
||||
|
||||
>Stylistic note: we recommend annotating your directives in your config file with a header about what the directive is doing.
|
||||
|
||||
## Structure and Terminology
|
||||
|
||||
Directives consist of three parts:
|
||||
|
||||
- **Location**: denoted by the field `from`, which document are we trying to transform. For swagger transformations, it's always `from: swagger-document`.
|
||||
|
||||
- **Filter**: denoted by the field `where`, contains the criteria to select the object.
|
||||
- An `operation` is filtered by
|
||||
- its path in the swagger's [`paths`][paths] object AND
|
||||
- it's HTTP verb
|
||||
- A `parameter` is filtered by:
|
||||
- its location in its `operation` (see above) OR
|
||||
- its name in the swagger's `parameters` object, if it's defined as a common parameter there (see the Common Parameters for Various Paths section [here][parameters] for more information)
|
||||
- A `model` can be filtered by:
|
||||
- its name in the [components or definitions][components] section OR
|
||||
- its location in its outer object, if defined within another object OR
|
||||
- its location in an operation, if defined within an operation
|
||||
- A `property` can be filtered by:
|
||||
- its location within its parent object
|
||||
|
||||
- **Transform**: denoted by the field `transform`, the actions we would like to be applied on the specified objects.
|
||||
|
||||
## Directive Scenarios
|
||||
|
||||
The following directives cover the most common tweaking scenarios for generation.
|
||||
|
||||
- [Operation Rename](#operation-rename "Operation Rename")
|
||||
- [Parameter Rename](#parameter-rename "Parameter Rename")
|
||||
- [Model Rename](#model-rename "Model Rename")
|
||||
- [Property Rename](#property-rename "Property Rename")
|
||||
- [Enum Value Rename](#enum-value-rename "Enum Value Rename")
|
||||
- [Change Description](#change-description "Change Description")
|
||||
|
||||
### Operation Rename
|
||||
|
||||
A common use case is renaming an operation. Say you have the following operation in your swagger:
|
||||
|
||||
```yaml
|
||||
...
|
||||
"paths": {
|
||||
"/vm": {
|
||||
"get": {
|
||||
"operationId": "getVirtualMachine",
|
||||
...
|
||||
}
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
and you'd like to rename it from `getVirtualMachine` to `getVM`. You would refer to this operation with the combination of its `path` and its http `verb`.
|
||||
As always, you use `from: swagger-document` to specify you're changing your swagger document. Finally, what you're transforming is the `"operationId"`.
|
||||
Putting this together, your directive looks like:
|
||||
|
||||
``` yaml
|
||||
### Directive renaming operation from "getVirtualMachine" to "getVM"
|
||||
directive:
|
||||
from: swagger-document
|
||||
where: '$.paths["/vm"].get'
|
||||
transform: >
|
||||
$["operationId"] = "getVM";
|
||||
```
|
||||
|
||||
### Parameter Rename
|
||||
|
||||
To select the parameter, you either refer to its location inside the operation it's defined within, or its name in the [common `parameters` section][parameters].
|
||||
We'll go over both in this example. In both cases, we'll be looking to rename parameter `id` to `identifier`.
|
||||
|
||||
#### Parameter defined in operation
|
||||
|
||||
```yaml
|
||||
...
|
||||
"paths": {
|
||||
"/vm": {
|
||||
"get": {
|
||||
"operationId": "getVirtualMachine"
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Referring to the parameter's location in the operation, our filter would be `where: '$.paths["/vm"].get.parameters[0]'`. We're changing the name of the parameter,
|
||||
so our transform would apply to the `name` field (or the [`x-ms-client-name`] field if we've defined one for the parameter). This becomes
|
||||
|
||||
``` yaml
|
||||
### Directive renaming "getVirtualMachine"'s parameter "id" to "identifier".
|
||||
directive:
|
||||
from: swagger-document
|
||||
where: '$.paths["/vm"].get.parameters[0]'
|
||||
transform: >
|
||||
$["name"] = "identifier";
|
||||
```
|
||||
|
||||
#### Parameter defined in the "Parameters" section
|
||||
|
||||
```yaml
|
||||
...
|
||||
"parameters": {
|
||||
"Id": {
|
||||
"name": "id",
|
||||
...
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
Now, we refer to the parameters location within the swagger's `parameters` object. This changes our filter to `where: '$.parameters["Id"]'`, and leads us
|
||||
to the following directive:
|
||||
|
||||
``` yaml
|
||||
### Directive renaming "getVirtualMachine"'s parameter "id" to "identifier".
|
||||
directive:
|
||||
from: swagger-document
|
||||
where: '$.parameters["Id"]'
|
||||
transform: >
|
||||
$["name"] = "identifier";
|
||||
```
|
||||
|
||||
### Model Rename
|
||||
|
||||
We have the following swagger:
|
||||
|
||||
```yaml
|
||||
...
|
||||
"definitions": {
|
||||
"VM": {
|
||||
"type": "object"
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
and we'd like to rename the model `VM` to `VirtualMachine`. We refer to the model with filter `where: #.definitions.VM`. Since the location we're trying to transform
|
||||
is listed as a key in the swagger dictionary and not a field, we change the model's name by adding in field [`x-ms-client-name`][x_ms_client_name]. Thus, our directive looks like
|
||||
|
||||
``` yaml
|
||||
### Directive renaming "VM" model to "VirtualMachine"
|
||||
directive:
|
||||
from: swagger-document
|
||||
where: '$.definitions.VM'
|
||||
transform: >
|
||||
$["x-ms-client-name"] = "VirtualMachine";
|
||||
```
|
||||
|
||||
### Property Rename
|
||||
|
||||
Let's say we want to rename the following property from `id` to `identifier`.
|
||||
|
||||
```yaml
|
||||
...
|
||||
"definitions": {
|
||||
"VM": {
|
||||
"type": "object"
|
||||
"properties": {
|
||||
"id": {
|
||||
...
|
||||
}
|
||||
}
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
We refer to the property based on its location in its parent object, giving us filter `where: #.definitions.VM.properties.id`. Similar to a [model](#model-rename "model"), we have to use
|
||||
[`x-ms-client-name`][x_ms_client_name] since there's no `name` field to change. This gives us
|
||||
|
||||
``` yaml
|
||||
### Directive renaming "id" property to "identifier"
|
||||
directive:
|
||||
from: swagger-document
|
||||
where: '$.definitions.VM.properties.id'
|
||||
transform: >
|
||||
$["x-ms-client-name"] = "identifier";
|
||||
```
|
||||
|
||||
### Enum Value Rename
|
||||
|
||||
Renaming an enum requires referencing the [`x-ms-enum`][x_ms_enum] used to define the enum. In this scenario, we're looking to change the name of an enum value from `AzureVM` to `AzureVirtualMachine`.
|
||||
As you can see from the swagger:
|
||||
|
||||
```yaml
|
||||
...
|
||||
"definitions": {
|
||||
"VM": {
|
||||
"type": "object"
|
||||
"properties": {
|
||||
"virtualMachineType": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"Azure_VM",
|
||||
...
|
||||
],
|
||||
"x-ms-enum": {
|
||||
"name": "VirtualMachineTypes",
|
||||
"values": [
|
||||
{
|
||||
"value": "Azure_VM"
|
||||
"name": "AzureVM"
|
||||
...
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
This gives us directive
|
||||
|
||||
``` yaml
|
||||
### Directive renaming enum AzureVM to AzureVirtualMachine
|
||||
directive:
|
||||
from: swagger-document
|
||||
where: '$.definitions.VM.properties.virtualMachineType.x-ms-enum.values[0]'
|
||||
transform: >
|
||||
$["name"] = "AzureVirtualMachine";
|
||||
```
|
||||
|
||||
Now, we would access the enum through `VirtualMachineTypes.AzureVirtualMachine` instead of `VirtualMachineTypes.AzureVM`.
|
||||
|
||||
### Change Description
|
||||
|
||||
Changing a description is very similar whether you're changing an operation's description or a model's description etc. The only thing that varies is how to refer to the object whose description your changing. Since this is covered in the previous examples, we won't do separate sections for this. Instead, we will show you how to change a property's description, which can be easily extended to another object, i.e. an operation.
|
||||
|
||||
Let's say we [renamed the property](#property-rename "renamed the property") from `id` to `identifier`, and we want to change all references in the description of `id` to `identifier`:
|
||||
|
||||
```yaml
|
||||
...
|
||||
"definitions": {
|
||||
"VM": {
|
||||
"type": "object"
|
||||
"properties": {
|
||||
"id": {
|
||||
"description": "The 'id' property is used to identify your VM instance.
|
||||
}
|
||||
}
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
We once again refer to the property's location as `where: #.definitions.VM.properties.id`, and we want to change the `description` field in the property. This gives uss
|
||||
|
||||
``` yaml
|
||||
### Directive changing references of 'id' to 'identifier' in the 'identifier' property's description
|
||||
directive:
|
||||
from: swagger-document
|
||||
where: '$.definitions.VM.properties.id'
|
||||
transform: >
|
||||
$["description"] = $["description].replace("'id'", "'identifier'");
|
||||
```
|
||||
|
||||
For language-specific directives, see the ones for:
|
||||
- [Python][python]
|
||||
|
||||
<!-- LINKS -->
|
||||
[python]: https://github.com/Azure/autorest.python/blob/autorestv3/docs/generate/directives.md
|
||||
[paths]: https://swagger.io/docs/specification/paths-and-operations/
|
||||
[parameters]: https://swagger.io/docs/specification/describing-parameters/
|
||||
[components]: https://swagger.io/docs/specification/components/
|
||||
[x_ms_client_name]: https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-client-name
|
||||
[x_ms_enum]: https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
# Generate Pets in Python
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
input-file: ../openapi/examples/pets.json
|
||||
python: true
|
||||
output-folder: generated/
|
||||
namespace: azure-pets
|
||||
```
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
# Java
|
||||
|
||||
These settings apply only when `--java` is specified on the command line.
|
||||
|
||||
``` yaml
|
||||
fluent: true
|
||||
```
|
||||
|
||||
## Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
namespace: com.microsoft.azure.pets.v1
|
||||
output-folder: java/pets/v1
|
||||
```
|
||||
|
||||
## Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
namespace: azure.pets.v2
|
||||
output-folder: java/pets/v2
|
||||
```
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
### General settings
|
||||
``` yaml
|
||||
tag: v2
|
||||
license-header: MICROSOFT_MIT_NO_VERSION
|
||||
```
|
||||
|
||||
### Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
input-file: pets.json
|
||||
```
|
||||
|
||||
### Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
input-file: petsv2.json
|
||||
```
|
||||
|
||||
## Python
|
||||
|
||||
See configuration in [readme.python.md](./readme.python.md)
|
||||
|
||||
## Java
|
||||
|
||||
See configuration in [readme.java.md](./readme.java.md)
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
# Python
|
||||
|
||||
These settings apply only when `--python` is specified on the command line.
|
||||
|
||||
``` yaml
|
||||
package-name: azure-pets
|
||||
```
|
||||
|
||||
## Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
namespace: azure.pets.v1
|
||||
output-folder: python/pets/azure-pets/azure/pets/v1
|
||||
```
|
||||
|
||||
## Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
namespace: azure.pets.v2
|
||||
output-folder: python/pets/azure-pets/azure/pets/v2
|
||||
```
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# Generate Pets in Python with Conditional Tags
|
||||
|
||||
### General settings
|
||||
|
||||
```yaml
|
||||
python: true
|
||||
package-name: azure-pets
|
||||
tag: v2
|
||||
```
|
||||
|
||||
### Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
input-file: pets.json
|
||||
namespace: azure.pets.v1
|
||||
output-folder: $(python-sdks-folder)/pets/azure-pets/azure/pets/v1
|
||||
```
|
||||
|
||||
### Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
input-file: petsv2.json
|
||||
namespace: azure.pets.v2
|
||||
output-folder: $(python-sdks-folder)/pets/azure-pets/azure/pets/v2
|
||||
```
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
# <img align="center" src="../images/logo.png"> Index of AutoRest Flags
|
||||
|
||||
## Shared Flags
|
||||
| Flag | Description | Python | .NET | Java | TS | Go
|
||||
|------------------|-------------|-------------|-------------|-------------|-------------|-------------
|
||||
| `--input-file=FILENAME` | Adds the given file to the list of input files for generation process | x | x | x | x | x
|
||||
|`--output-folder=DIRECTORY`|The location for generated files. If not specified, uses `./generated` as the default| x | x | x | x | x
|
||||
|`--clear-output-folder`|Clear all contents from our output folder before outputting your newly generated code into that folder. Defaults to `false`.| x | x | x | x | x
|
||||
|`--project-folder=DIRECTORY`|Use this flag if you have a project folder that will contain both generated code and existing code you would like to persist. You can then define the output folder relative to this project folder, i.e. `output-folder: $(project-folder)/generated`.| x | x | x | x | x
|
||||
|`--add-credential`|If specified, the generated client will require a credential to make network calls. See [TODO] for information on how to authenticate to our generated clients. Forced to be `true` if `--azure-arm` is set, otherwise defaults to `false`.| x | No flag for `--add-credential`, will add credential param for a `TokenCredential` if `--azure-arm` is `true`. | No flag for `--add-credential`, gets whether to add credential from value of `--credential-types`. Defaults to false.| Is called `--add-credentials`. Defaults to false. | No flag, looks in `authenticationRequired` field in the swagger. Does not automatically set to true in azure-arm.
|
||||
|`--credential-scopes=VALUE(S)`|Specify the scopes over which the credential functions (see previous flag `--add-credential` for adding client credentials). This is tied with `BearerTokenCredentialPolicy`. If generating management plane code (see `--azure-arm` flag directly below), we default the scope to `'https://management.azure.com/.default'`. If not, we highly recommend you use this flag if `--add-credential` is specified. If you don't generate with scopes in this case, it forces your SDK users to pass credential scopes themselves when calling your code. You can pass multiple values in using CSV format.| x | No flag for credential scopes. Currently only sets `TokenCredential` in mgmt mode. In mgmt mode's case, the credential scope is forced to `{endpoint}/.default`. In mgmt mode, this endpoint (which is gotten from the swagger), is `https://management.azure.com`| Currently doesn't default to ARM scope in mgmt mode | | `--credential-scope`
|
||||
|`--license-header=LICENSE_HEADER`|Specify the type of license header for your files. Common values include `MICROSOFT_MIT_NO_VERSION` and `MICROSOFT_MIT_NO_CODEGEN` TODO: list of all possible values and default| x | x | x | x | x
|
||||
|`--namespace=NAMESPACE`|Sets the namespace to use for the generated code| x | x | x | |
|
||||
|`--azure-arm`|generates control plane (Azure Resource Manager) code. Use this if you're generate SDKs for people to manage their Azure resources. See our [mgmt plane section][mgmt_plane_section] for more info. Defaults to `false`.| x | x | x | x | Uses flag `--openapi-type=arm` to specify
|
||||
|`--head-as-boolean`|With this flag, HEAD calls to non-existent resources (404) will not raise an error. Instead, if the resource exists, we return `true`, else `false`. Forced to be `true` if `--azure-arm` is set, otherwise defaults to `false`.| x | x ||| Go default is always `false`.
|
||||
|`--title=NAME`|Override the service client's name listed in the swagger under `title`.| x | x | x | x | x
|
||||
|`--description=DESCRIPTION`|Override the service client's description listed in the swagger under the top level `description`.| x | x | x | x | x
|
||||
|`--client-side-validation`|Whether you want the SDK to perform validation on inputs and outputs, based on swagger information. Recommended to be `false` for track 2 code, since we want the network to validate instead. Defaults to `false`.| x | x | calls it `--client-side-validations` | | x
|
||||
|`--package-name=NAME`|The name of your package. This is the name your package will be published under.| x | | |x |
|
||||
|`--package-version=VERSION`|The semantic versioning of your generated SDK (i.e., `1.0.0`). Not to be confused with the version of the service you're creating an SDK for. If no version is specified, AutoRest will not create a new version file. Generally not necessary if you are going to wrap the generated code before exposing to users.| Needs to be specified if `--basic-setup-py` is specified. | Currently can't generate version for track 2|Default is `1.0.0-beta.1`. Only available in `fluent` mode.|Currently can't set version for track 2| Defaults to `1.0.0`|
|
||||
|`--trace`|Whether to natively support tracing libraries, such OpenCensus or OpenTelemetry. See this [tracing quickstart][tracing_quickstart] for an overview. Defaults to `false`.| x | | | x|
|
||||
|
||||
## Python Flags
|
||||
| Flag | Description
|
||||
|------------------|-------------
|
||||
|`--python-sdks-folder=DIRECTORY`| The path to the root directory of your [`azure-sdk-for-python`][azure_sdk_for_python] clone. Be sure to note that we include `sdk` in the folder path.
|
||||
|`--black`| Runs [black][black] formatting on your generated files. Defaults to `false`.
|
||||
|`--basic-setup-py`|Whether to generate a build script for setuptools to package your SDK. See [here][setup_py] for more information about a `setup.py` file. Defaults to `false`, generally not suggested if you are going to wrap the generated code before exposing to users. Needs `--package-version` to be specified. Defaults to `false`.
|
||||
|`--multiapi`|Whether to generate a multiapi client. See [our multiapi section][multiapi_section] for more information. Defaults to `false`.
|
||||
|`--default-api=VALUE`|In the case of `--multiapi`, you can override the default service API version with this flag. If not specified, we use the latest GA service version as the default API.
|
||||
|`--keep-version-file`|Whether you want to override the current version file in your package or not. Defaults to `false`.
|
||||
|`--no-namespace-folders`|Specify if you don't want pkgutil-style namespace folders. See [here][namespace_folders] for more information on pkgutil namespace folders. Defaults to `false`.
|
||||
|`--credential-default-policy-type=BearerTokenCredentialPolicy\|AzureKeyCredentialPolicy`|Specify the default credential policy (authentication policy) for your client. Use in conjunction with `--add-credential`. Currently only supports [`BearerTokenCredentialPolicy`][bearer_token_credential_policy] and [`AzureKeyCredentialPolicy`][azure_key_credential_policy]. Default value is `BearerTokenCredentialPolicy`. `--credential-scopes` is tied with `BearerTokenCredentialPolicy`, do not pass them in if you want `AzureKeyCredentialPolicy`.
|
||||
|`--credential-key-header-name=NAME`|The name of the header which will pass the credential. Use if you have `--credential-default-policy-type` set to [`AzureKeyCredentialPolicy`][azure_key_credential_policy]. For example, if generating cognitive services code, you might use `--credential-key-header-name=Ocp-Apim-Subscription-Key`.
|
||||
|
||||
## .NET Flags
|
||||
|
||||
| Flag | Description
|
||||
|------------------|-------------
|
||||
|`--library-name=NAME`|The name of your library. This is what will be displayed on NuGet.
|
||||
|`--shared-source-folders=VALUE(S)`|Pass shared folder paths through here. Common values point to the [shared generator assets][shared_generator_assets] and [shared azure core assets][shared_azure_core_assets] in [autorest.csharp][autorest_csharp
|
||||
|`--public-clients`|Whether to have your client public. Defaults to `false`.
|
||||
|`--model-namespace`|Whether to add a separate namespace of Models, more specifically adding `{value-from-namespace-flag}.Models`. Defaults to `true`.
|
||||
|
||||
## Java Flags
|
||||
|
||||
| Flag | Description
|
||||
|------------------|-------------
|
||||
|`--azure-libraries-for-java-folder=DIRECTORY` | The path to the root directory of your [`azure-sdk-for-java`][azure_sdk_for_java] clone. Be sure to note that we include `sdk` in the folder path.
|
||||
|`--fluent=LITE\|PREMIUM`|Enables Java's fluent generator, generating a set of fluent Java interfaces for a guided and convenient user experience for the client library. Currently used by Azure management libraries. `LITE` for Fluent Lite; `PREMIUM` for Fluent Premium. Default is `PREMIUM` if provided as other values. See [the java docs][fluent_docs] for all of the Fluent specific flags.
|
||||
|`--regenerate-pom`|Whether to regenerate the pom file in your project. See [here][pom] for more information on what a pom file is. Defaults to `false`.
|
||||
|`--generate-client-as-impl`|Append "Impl" to the names of service clients and method groups and place them in the `implementation` sub-package. Defaults to `false`.
|
||||
|`--generate-client-interfaces`|Generates interfaces for all the "Impl"s. Forces `--generate-client-as-impl` to `true`, and generates an interface for it as well. Defaults to `false`.
|
||||
|`--generate-sync-async-clients`|Generates sync and async convenience layer clients for all the "Impl"s. Forces `--generate-client-as-impl` to `true`. Defaults to `false`.
|
||||
|`--implementation-subpackage=NAME`|The sub-package that the Service client and Method Group client implementation classes will be put into. Defaults to `implementation`.
|
||||
|`--models-subpackage=NAME`|The sub-package that Enums, Exceptions, and Model types will be put into. Defaults to `models`.
|
||||
|`--add-context-parameter`|Indicates whether the [`com.azure.core.util.Context`][java_context] parameter should be included in generated proxy methods. Use if you want to pass arbitrary data (key-value pairs) to pipeline policies. Defaults to `false`.
|
||||
|`--context-client-method-parameter`|Indicates whether the `com.azure.core.util.Context` parameter should also be included in generated client methods. Forces `--add-context-parameter` to `true`. Defaults to `false`.
|
||||
|`--sync-methods=all\|essential\|none`|Specifies mode for generating sync wrappers. Supported values are <br> `essential` - generates only one sync returning body or header (default) <br> `all` - generates one sync method for each async method<br> `none` - does not generate any sync methods
|
||||
|`--required-parameter-client-methods`|Indicates whether client method overloads with only required parameters should be generated. Defaults to `false`.
|
||||
|`--custom-types-subpackage=VALUE`|The sub-package that the custom types should be generated in. The types that custom types reference, or inherit from will also be automatically moved to this sub-package. **Recommended usage**: You can set this value to `models` and set `--models-subpackage=implementation.models`to generate models to `implementation.models` by default and pick specific models to be public through `--custom-types`.
|
||||
|`--custom-types=VALUE(S)`|Specifies a list of files to put in the package specified in `--custom-types-subpackage`. You can pass multiple values in using CSV format.
|
||||
|`--client-type-prefix=PREFIX`|The prefix that will be added to each generated client type.
|
||||
|`--model-override-setter-from-superclass`|Indicates whether to override the superclass setter method in model. Defaults to `false`.
|
||||
|`--non-null-annotations`|Whether or not to add the `@NotNull` annotation to required parameters in client methods. Defaults to `false`.
|
||||
|`--client-logger`|Whether the client should log by default. Defaults to `false`.
|
||||
|`--required-fields-as-ctor-args`|Whether an object's required fields should be specified as arguments to its constructor. Defaults to `false`.
|
||||
|`--service-interface-as-public`|Whether the service's interface should be set as public. Defaults to `false`.
|
||||
|`--artifact-id`|The name of your project jar without its version. See [here][artifact_id] for more information about an artifact id.
|
||||
|`--credential-types=TokenCredential\|AzureKeyCredential\|None`|The type of credential if `--add-credential` is specified. Defaults to `None`.
|
||||
|`--customization-jar-path=FILEPATH`|Pass in the path to your .jar file that contains customizations to the output files. This will allow AutoRest to dynamically load the class you provide in `--customization-class`.
|
||||
|`--customization-class=NAME`|Use in conjunction with `--customization-jar-path`. That flag tells AutoRest where to look for your custom class, while `--customization-class` tells AutoRest the name of your custom class.
|
||||
|
||||
## TS Flags
|
||||
|
||||
| Flag | Description
|
||||
|------------------|-------------
|
||||
|`--source-code-folder-path=DIRECTORY`|Where to output the generated code inside the `output-folder`. Use in the scenario when you are going to write a convenience layer on top of the generated code. Defaults to `src`.| | || x|
|
||||
|`--generate-metadata`|Whether to generate extra metadata in your package. For instance, generates a README file, license file etc if set to `true`. Defaults to `false`.
|
||||
|`--tracing-spanprefix=SPAN_PREFIX`|If you are tracing (passing in flag `--trace`), and you want to overwrite the span prefix AutoRest assigns, use this flag.
|
||||
|`--disable-async-iterators`|Whether to generate pageable methods as [AsyncIterators][ts_async_iterator]. Defaults to `true`.
|
||||
|
||||
## Go flags
|
||||
|
||||
| Flag | Description
|
||||
|------------------|-------------
|
||||
|`--module=NAME`|The name of the module. This is the name your module will be published under.
|
||||
|`--file-prefix=PREFIX`|Optional prefix to file names. For example, if you set your file prefix to "zzz", all generated code files will begin with "zzz".
|
||||
|`--openapi-type=arm\|data-plane`|Specify if you want to generate `data-plane` code or `arm` code.
|
||||
|`--armcore-connection`|If set to `true`, we output the code with the `Connection` type specified in [`armcore`][armcore_connection]. If not, we output a new `Connection` constructor with the generated code. Defaults to `false`.
|
||||
|
||||
## Debugging flags
|
||||
|
||||
| Flag | Description | Python | .NET | Java | TS | Go
|
||||
|------------------|-------------|-------------|-------------|-------------|-------------|-------------
|
||||
|`--verbose`| Log verbose-level information during generation time | x | x | x | x | x
|
||||
|`--debug`| Log debug-level information during generation time | x | x | x | x | x
|
||||
|`--{language-generator}-debugger`| Debug into a specific language's code. See our [debugging docs][debugging] to see if there are extra steps needed to for your language generator of choice | x | x | x | x | x
|
||||
|`--save-inputs`|Whether to save the configuration files (i.e. `Configuration.json` or `codeyaml.json`). Defaults to `false`.| | x| | | | |
|
||||
|
||||
|
||||
## Deprecated / Not-Recommended Flags
|
||||
|
||||
| Flag | Description | Python | .NET | Java | TS | Go
|
||||
|------------------|-------------|-------------|-------------|-------------|-------------|-------------
|
||||
|`--payload-flattening-threshold=NUMBER`|The maximum number of properties in the request body. If the number of properties in the request body is less than or equal to this value, these properties will be represented as method arguments. Not recommended because it can cause surprise breaking changes when adding properties. | x | x | x | x | x
|
||||
|`--add-credentials`|Same as flag `--add-credential`, renamed because we only add one `credential` param in this case. | x | x | x | x | x
|
||||
|
||||
<!-- LINKS -->
|
||||
[tracing_quickstart]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core-tracing-opentelemetry/README.md
|
||||
[azure_sdk_for_python]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk
|
||||
[mgmt_plane_section]: ./readme.md#generating-management-plane-code
|
||||
[setup_py]: https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py
|
||||
[multiapi_section]: ./readme.md#generating-multiapi-code
|
||||
[namespace_folders]: https://packaging.python.org/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages
|
||||
[bearer_token_credential_policy]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/latest/azure.core.pipeline.policies.html#azure.core.pipeline.policies.BearerTokenCredentialPolicy
|
||||
[azure_key_credential_policy]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/latest/azure.core.pipeline.policies.html#azure.core.pipeline.policies.AzureKeyCredentialPolicy
|
||||
[shared_generator_assets]: https://github.com/Azure/autorest.csharp/tree/feature/v3/src/assets/Generator.Shared
|
||||
[shared_azure_core_assets]: https://github.com/Azure/autorest.csharp/tree/feature/v3/src/assets/Azure.Core.Shared
|
||||
[autorest_csharp]: https://github.com/Azure/autorest.csharp
|
||||
[azure_sdk_for_java]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk
|
||||
[pom]: https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#what-is-a-pom
|
||||
[java_context]: https://azuresdkdocs.blob.core.windows.net/$web/java/azure-core/1.0.0/index.html?com/azure/core/util/Context.html
|
||||
[artifact_id]: https://maven.apache.org/guides/mini/guide-naming-conventions.html
|
||||
[fluent_docs]: https://github.com/Azure/autorest.java#additional-settings-for-fluent
|
||||
[armcore_connection]: https://github.com/Azure/azure-sdk-for-go/blob/master/sdk/armcore/connection.go
|
||||
[debugging]: ../troubleshooting.md#debugging
|
||||
[black]: https://pypi.org/project/black/
|
||||
[ts_async_iterator]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-3.html#async-iterators
|
||||
|
|
@ -1,10 +1,4 @@
|
|||
|
||||
# Working with Swagger Specifications
|
||||
|
||||
> NOTE: OpenAPI is the official name of the specification that was formerly called "Swagger".
|
||||
|
||||
AutoRest processes OpenAPI specifications following the [OpenAPI RESTful API Documentation Specification](Swagger-spec2.0)
|
||||
API descriptions that are valid according to the schema can produce client libraries that are not very user-friendly. Here are some techniques to apply in authoring OpenAPI that improve the usability of the client generated by AutoRest.
|
||||
# <img align="center" src="../images/logo.png"> How AutoRest Generates Code From an OpenAPI Definition
|
||||
|
||||
## Contents
|
||||
- [Data Types](#data-types)
|
||||
|
|
@ -71,7 +65,7 @@ public partial class Pet
|
|||
To represent `byte` arrays in the generated code, the property of the OpenAPI definition should have `string` as its type and `byte` as its format. This indicates binary data that will be represented as a base64-encoded string in requests and responses. The generated client will automatically do this encoding when processing requests and responses.
|
||||
|
||||
- **`DateTime`**
|
||||
AutoRest generates `DateTime` typed properties in generated C# code for OpenAPI properties that have `string` as the type and `date-time` as the format. Note: it's possible to generate these properties as `DateTimeOffset` in C# when `-useDateTimeOffset` parameter is passed via command line.
|
||||
AutoRest generates `DateTime` typed properties in generated C# code for OpenAPI properties that have `string` as the type and `date-time` as the format.
|
||||
|
||||
- **`int` / `long`**
|
||||
Both `int` and `long` properties in the generated code correspond to `integer` types in OpenAPI properties. If the format of the OpenAPI property is `int32`, `int` will be generated; if the format is `int64`, `long` will be generated. If the format field of the OpenAPI property is not set, AutoRest use format `int32`.
|
||||
|
|
@ -169,10 +163,10 @@ public partial class Pet
|
|||
### Dictionaries
|
||||
AutoRest generates dictionaries (or hash maps in some contexts) using `additionalProperties` from [JSON-Schema Draft 4][JSON-schema-validation-properties]. The additionalProperties element should specify the OpenAPI schema of the values in the dictionary . The keys of the generated dictionary will be of type `string`.
|
||||
|
||||
There are two basic patterns when generating dictionaries in AutoRest.
|
||||
There are two basic patterns when generating dictionaries in AutoRest.
|
||||
|
||||
#### Dictionaries as a member.
|
||||
A dictionary can be generated as a member in a object schema, when there are no `properties` defined, the dictionary will be generated for the entire member.
|
||||
A dictionary can be generated as a member in a object schema, when there are no `properties` defined, the dictionary will be generated for the entire member.
|
||||
|
||||
The following definition
|
||||
```json
|
||||
|
|
@ -228,7 +222,7 @@ public partial class Pet
|
|||
```
|
||||
|
||||
#### Dictionaries as a catch-all for unlisted properties.
|
||||
A dictionary can be also generated as way of accepting data for unlisted properties. The code generator (c#, in this case) will emit code that instructs the deserializer to send all unspecified values in the object to the generated `AdditionalProperties` member
|
||||
A dictionary can be also generated as way of accepting data for unlisted properties. The code generator (c#, in this case) will emit code that instructs the deserializer to send all unspecified values in the object to the generated `AdditionalProperties` member
|
||||
|
||||
The code :
|
||||
|
||||
|
|
@ -236,12 +230,12 @@ The code :
|
|||
definitions:
|
||||
MyResponseObject:
|
||||
type: object
|
||||
properties:
|
||||
someProperty:
|
||||
properties:
|
||||
someProperty:
|
||||
type: string
|
||||
# because this object has a property, additionalProperties becomes a catch-all for
|
||||
# because this object has a property, additionalProperties becomes a catch-all for
|
||||
# any properties in the response that aren't specified.
|
||||
additionalProperties:
|
||||
additionalProperties:
|
||||
type: string
|
||||
```
|
||||
|
||||
|
|
@ -276,7 +270,7 @@ public partial class MyResponseObject
|
|||
[JsonProperty(PropertyName = "someProperty")]
|
||||
public string SomeProperty { get; set; }
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### Constants
|
||||
AutoRest generates constant value for _required_ parameters and properties defined with _one_ enum value. Constant operation parameters are not exposed to the end user and are injected in the method body. Constant definition properties are also automatically added to the payload body.
|
||||
|
|
@ -351,7 +345,7 @@ public async Task<HttpOperationResponse> MyOperationWithHttpMessagesAsync(Dictio
|
|||
#### Inheritance
|
||||
AutoRest builds inheritance between types if an `allOf` field is specified in a OpenAPI definition with ONLY one reference to another OpenAPI definition. The following example demonstrate a `Cat` type inheriting a `Pet` with its `allOf` set to `[{"$ref": "Pet"}]`.
|
||||
|
||||
> Note: Only `allOf` fields with one schema reference will be treated as inheritance. If `allOf` contains more than one schema that has `"$ref"` as the key, the properties from the referenced schemas will be composed without inheritance. However, if an `allOf` contains multiple inline schemas and a single schema reference, the generated model type will use inheritance.
|
||||
> Note: Only `allOf` fields with one schema reference will be treated as inheritance. If `allOf` contains more than one schema that has `"$ref"` as the key, the properties from the referenced schemas will be composed without inheritance. However, if an `allOf` contains multiple inline schemas and a single schema reference, the generated model type will use inheritance.
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
|
|
@ -451,7 +445,7 @@ The generated models in C# code are nearly identical, with `objectType` property
|
|||
public partial class MyClient : ServiceClient<AutoRestComplexTestService>, IAutoRestComplexTestService
|
||||
{
|
||||
...
|
||||
|
||||
|
||||
/// <summary>
|
||||
/// Initializes client properties.
|
||||
/// </summary>
|
||||
|
|
@ -460,7 +454,7 @@ public partial class MyClient : ServiceClient<AutoRestComplexTestService>, IAuto
|
|||
...
|
||||
SerializationSettings.Converters.Add(new PolymorphicSerializeJsonConverter<Pet>("objectType"));
|
||||
DeserializationSettings.Converters.Add(new PolymorphicDeserializeJsonConverter<Pet>("objectType"));
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -716,7 +710,7 @@ if ((int)_statusCode != 200)
|
|||
|
||||
See [Error Handling](../../client/error.md) for details on how to catch and use the exceptions from generated clients.
|
||||
|
||||
### DEPRECATED - Composite Clients
|
||||
### DEPRECATED - Composite Clients
|
||||
AutoRest supports a concept of a composite client where multiple OpenAPI documents are merged together to generate a single ServiceClient. To use this feature the OpenAPI documents need to conform to the following rules:
|
||||
|
||||
1. All OpenAPI documents must share the same `host` and `basePath` values
|
||||
|
|
@ -724,12 +718,12 @@ AutoRest supports a concept of a composite client where multiple OpenAPI documen
|
|||
3. All global client parameters with same names must be identical
|
||||
4. Methods with the same `operationId` but different signature are allowed. However, there should be no methods with the same `operationId` and same signature.
|
||||
|
||||
For Azure generators, composite clients will not have ApiVersion global property but will instead have apiVersion operation constants.
|
||||
For Azure generators, composite clients will not have ApiVersion global property but will instead have apiVersion operation constants.
|
||||
|
||||
#### DEPRECATED: Generating Composite Clients
|
||||
In order to generate a composite client a custom metadata needs to be created.
|
||||
|
||||
**Schema**:
|
||||
**Schema**:
|
||||
|
||||
Field Name | Type | Description
|
||||
---|:---:|---
|
||||
|
|
@ -758,7 +752,7 @@ A `CompositeSwagger` modeler should be used to generate composite clients. For e
|
|||
autorest.exe -modeler CompositeSwagger -input compositeDoc.json -output C:\Temp -codeGenerator CSharp
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Extensions
|
||||
AutoRest supports a number of extensions used to configure generated clients. Please refer to [Swagger Extensions](../../extensions/readme.md) document for details.
|
||||
|
||||
|
|
@ -0,0 +1,398 @@
|
|||
# <img align="center" src="../images/logo.png"> Generating Clients with AutoRest
|
||||
|
||||
This guide tells you how to generate code from your OpenAPI definition using AutoRest. We'll take this incrementally, working
|
||||
on first how to generate a single file, then how to generate with a configuration file, and keep taking it from there.
|
||||
|
||||
The command line usage of AutoRest boils down to the following:
|
||||
> `autorest [config-file.md | config-file.json | config-file.yaml] [additional options]`
|
||||
|
||||
We'll be building upon this in our individual sections.
|
||||
|
||||
## Introduction: Flags
|
||||
|
||||
### Language flags
|
||||
|
||||
AutoRest has varying levels of support for the following languages. When generating code, we always want to specify what language we
|
||||
want our generated code to have, and we specify our language through a command line flag
|
||||
|
||||
| Language | Description |
|
||||
|------------------|-------------|
|
||||
|`--python`|Python|
|
||||
|`--csharp`|C# / .NET code|
|
||||
|`--java`|Java|
|
||||
|`--typescript`|Typescript|
|
||||
|`--go`|Golang|
|
||||
|No flag yet|Swift|
|
||||
|
||||
### Common flags
|
||||
|
||||
For a full-set of flags, go to our [flag index][flags]
|
||||
|
||||
| Option | Description |
|
||||
|------------------|-------------|
|
||||
|`--input-file=FILENAME`|Adds the given file to the list of input files for generation process|
|
||||
|`--output-folder=DIRECTORY`|The location for generated files. If not specified, uses `./generated` as the default|
|
||||
|`--clear-output-folder`|Clear all contents from our output folder before outputting your newly generated code into that folder|
|
||||
|`--namespace=NAMESPACE`|sets the namespace to use for the generated code|
|
||||
|`--add-credential`|If specified, the generated client will require a credential to make network calls. See [TODO] for information on how to authenticate to our generated clients|
|
||||
|`--tag=VALUE`|Preferred way to have conditional configurations. I.e., in my configuration file, I can set the `input-file` equal to different values depending on the `VALUE` passed through the `tag` flag. See our [Adding Tags When Generating](#adding-tags-when-generating "Adding Tags When Generating") section for more information|
|
||||
|
||||
## Most Basic: Generating with a Single File on the Command Line
|
||||
|
||||
The first step in an AutoRest journey usually starts with generating a single OpenAPI file. We will also show
|
||||
how to set options during generation by building up our command-line step-by-step.
|
||||
|
||||
The first step here is to have your OpenAPI file definition of your client ([docs][openapi_introduction]) on how to do that).
|
||||
This example will use an example OpenAPI definition found [here][pets_swagger], so feel free to follow along with
|
||||
our sample code. To get things started, the command that starts AutoRest on the command line is `autorest`, so this is what our command line
|
||||
looks like to start with:
|
||||
|
||||
```
|
||||
autorest
|
||||
```
|
||||
|
||||
Next, we want to tell AutoRest which swagger file to generate. We do this by passing our swagger file through the `--input-file` flag, see [common
|
||||
flags](#common-flags "common flags") for a description of its uses. Adding this to our command, we have
|
||||
|
||||
```
|
||||
autorest --input-file=pets.json
|
||||
```
|
||||
|
||||
We also need to tell AutoRest what language we want our SDK to be in, which we specify using our [language flags](#language-flags "language flags"). For the sake of this example,
|
||||
let's say we want to generate Python code. Adding this to our command line, we get
|
||||
|
||||
```
|
||||
autorest --input=file=pets.json --python
|
||||
```
|
||||
|
||||
In our final step, we can tell AutoRest where to output the generated SDK. By default AutoRest generates files in output folder `./generated`. However, we can
|
||||
modify the output folder using flag `--output-folder` (once again, see [common
|
||||
flags](#common-flags "common flags") for more information). Putting this all together, we have:
|
||||
|
||||
```
|
||||
autorest --input-file=pets.json --python --output-folder=myFolder/
|
||||
```
|
||||
|
||||
There are many other flags you can specify when generating. As an add-on, let's say we want to generate our code under the namespace `pets`. This gives us:
|
||||
|
||||
```
|
||||
autorest --input-file=pets.json --python --output-folder=myFolder/ --namespace=pets
|
||||
```
|
||||
And this concludes our basic example of generating with AutoRest. Continue reading to the next section to see our recommend way of generating AutoRest.
|
||||
|
||||
## Keeping your options in one place: the preferred option
|
||||
|
||||
This section goes over the most common, and the preferred way of generating with AutoRest: that is, generating with a configuration file.
|
||||
With a configuration file, we can move most of our flags from the command line into our configuration file, while still allowing
|
||||
us the ability to override the configuration file settings from the command line. This both simplifies our command line for generation,
|
||||
and allows us to have a standardized set of flags to generate your OpenAPI documents with.
|
||||
|
||||
As you can see in the above example, having to include these flags (i.e. `--input-file`, `--output-folder` etc) every time you generate can be cumbersome,
|
||||
and if you're trying to have every AutoRest generation standardized, a tiny typo can make a big difference. This is where a configuration file comes in.
|
||||
With a configuration file, we can add most, if not all of these flags into one file, where they can persist.
|
||||
|
||||
Lets start with our command line from the previous example, and work on moving these flags into a config file.
|
||||
|
||||
```
|
||||
autorest --input-file=pets.json --python --output-folder=myFolder/ --namespace=pets
|
||||
```
|
||||
|
||||
First step is to create our configuration file. The preferred name for a configuration file is `readme.md`, so you may hear these terms interchangeably.
|
||||
|
||||
Once your configuration file is created, we can work on moving our flags into the config file. We tell AutoRest what flags we want using `yaml` code chunks in the
|
||||
readme.
|
||||
|
||||
We start building up the skeleton of our configuration file by adding our `yaml` code block.
|
||||
````
|
||||
```yaml
|
||||
```
|
||||
````
|
||||
|
||||
Now, we'll start moving the flags into the `yaml` code block. Adding the input file becomes
|
||||
````
|
||||
```yaml
|
||||
input-file: pets.json
|
||||
```
|
||||
````
|
||||
We also want our code to be generated in python, so let's add that to the config as well.
|
||||
|
||||
````
|
||||
```yaml
|
||||
input-file: pets.json
|
||||
python: true
|
||||
```
|
||||
````
|
||||
Finally, let's add our remaining 2 flags.
|
||||
|
||||
````
|
||||
```yaml
|
||||
input-file: pets.json
|
||||
python: true
|
||||
output-folder: myFolder/
|
||||
namespace: azure-pets
|
||||
```
|
||||
````
|
||||
|
||||
Now, all of our flags are transferred into our configuration file! We've also included this final config file in our [examples][basic_example].
|
||||
|
||||
Having a configuration file doesn't mean you aren't allowed to specify flags on the command line, however, we recommend moving all flags into the config file, and only
|
||||
specifying flags on the command line if you're looking to override the values in the config file.
|
||||
|
||||
Your command line is now just
|
||||
`autorest readme.md`
|
||||
|
||||
And that's it!
|
||||
|
||||
## Adding Tags When Generating
|
||||
|
||||
Say you only want certain configurations if a specific tag is included on the command line. The most common use case for this is having different versions of swagger files,
|
||||
and wanting to toggle between generating both versions.
|
||||
|
||||
Let's start by examining what behavior we want to have when generating. The suggested way of toggling between versions on the command line is to specify a value in the `tag` flag.
|
||||
Let's say we want to generate our first [pets.json][pets_swagger] if you specify `--tag=v1`, and we want to generate our second [petsv2.json][pets_v2_swagger]
|
||||
if `--tag=v2` is specified on the command line. Let's go about putting in the markdown code to make this possible.
|
||||
|
||||
Starting with the flags we wantin both cases, we add in a `yaml` code block with no condition for entry.
|
||||
````
|
||||
### General settings
|
||||
|
||||
```yaml
|
||||
python: true
|
||||
package-name: azure-pets
|
||||
```
|
||||
````
|
||||
|
||||
In the `yaml` code blocks we have in our markdown file, we can add conditional blocks, which we only enter if a specific value is passed for a specific flag. In this case, we want our `input-file`
|
||||
to be `pets.json`, if `--tag=v1` is specified on the command line, and if `--tag=v2` is specified, we want our `input-file` to be `petsv2.json`. Finally, we also want different namespaces for each
|
||||
of these versions, and different output folders, so both can be allowed to persist at the same time.
|
||||
|
||||
Our code block for `tag=v1` thus looks like this
|
||||
````
|
||||
### Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
|
||||
input-file: pets.json
|
||||
namespace: azure.pets.v1
|
||||
output-folder: $(python-sdks-folder)/pets/azure-pets/azure/pets/v1
|
||||
```
|
||||
````
|
||||
> Note: It is highly recommended to comment your conditional `yaml` blocks with the conditions required to enter. This is because the `yaml` conditionals don't show up in rendered
|
||||
markdown, so comments are needed for visibility.
|
||||
|
||||
Similarly, our `tag=v2` code block will look like:
|
||||
````
|
||||
### Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
|
||||
input-file: petsv2.json
|
||||
namespace: azure.pets.v2
|
||||
output-folder: $(python-sdks-folder)/pets/azure-pets/azure/pets/v2
|
||||
```
|
||||
````
|
||||
|
||||
Finally, let us say we want `v2` to be generated by default, and `v1` only to be generating if `--tag=v1` is specified on the command line. We can add into our `General settings` `tag: v2`. This way,
|
||||
unless we override the value of `tag` by specifying `--tag=v1` on the command line, `tag` will be `v2`, and we will enter that conditional `yaml` code block by default. Updating our `General settings`, we get
|
||||
````
|
||||
### General settings
|
||||
|
||||
```yaml
|
||||
python: true
|
||||
output-folder: myFolder/
|
||||
tag: v2
|
||||
```
|
||||
````
|
||||
|
||||
Putting this all together, we get the [following config file][tags_readme], and to generate v1, our command line is `autorest readme.md --tag=v1 --python-sdks-folder={path to local clone of azure-sdk-for-python/sdk}`, while generating v2, our command line
|
||||
is just `autorest readme.md --python-sdks-folder={path to local clone of azure-sdk-for-python/sdk}` since `tag`'s default value is `v2`.
|
||||
|
||||
## Generating in Multiple Languages
|
||||
|
||||
A common occurrence is wanting to generate your SDK in multiple languages. Since flags can vary across languages (i.e., certain flags are specific to certain languages), we commonly add conditional sections
|
||||
for each language. In this example, we will show how to generate in both Java and Python. In situations like this, it is preferred to have one main
|
||||
language agnostic configuration file titled `readme.md`, where you list the configuration you want regardless of language. Then, you create a configuration file for every language you want with the language name in the path. In this case, we would create a `readme.java.md`, and a `readme.python.md`. These configuration files will be linked to from the main `readme.md`.
|
||||
|
||||
Let's start with the configurations we want in the main `readme.md`. Following from the [previous example](#adding-tags-when-generating), we want to generate [pets.json](../../openapi/examples/pets.json) if `--tag=v1` is specified on the command line, and [petsv2.json](../../openapi/examples/petsv2.json) if `--tag=v2` is specified, regardless of which language we're generating in. We also need to link to our `readme.python.md` and `readme.java.md` from this main readme.
|
||||
|
||||
This gives us the following `readme.md`:
|
||||
|
||||
````
|
||||
### General settings
|
||||
|
||||
```yaml
|
||||
tag: v2
|
||||
license-header: MICROSOFT_MIT_NO_VERSION
|
||||
```
|
||||
|
||||
### Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
input-file: pets.json
|
||||
```
|
||||
|
||||
### Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
input-file: petsv2.json
|
||||
```
|
||||
|
||||
## Python
|
||||
|
||||
See configuration in [readme.python.md](./readme.python.md)
|
||||
|
||||
## Java
|
||||
|
||||
See configuration in [readme.java.md](./readme.java.md)
|
||||
````
|
||||
|
||||
Let's now discuss what's going to be different between the two languages.
|
||||
|
||||
1. Location of the output: We want our sdks to go into separate locations based on language. The location will also vary based off of whether we're generating `v1` or `v2` (since we want both versions to exist), so we need individual conditional yaml blocks.
|
||||
|
||||
>Note: If you're developing with our Azure SDK repos, you can follow these steps:
|
||||
> - We would want our Python sdk to go into [`azure-sdk-for-python`][azure_sdk_for_python], and our Java sdk to go into [`azure-sdk-for-java`][azure_sdk_for_java].
|
||||
> - For Python, we use the flag `--python-sdks-folder` to indicate the location of our local [`azure-sdk-for-python`][azure_sdk_for_python] clone. Your output folder would be relative to `python-sdks-folder`, the location of which you would pass on the command line. I.e., your `output-folder` would look like `{python-sdks-folder}/pets/azure-pets`.
|
||||
> - For Java, we indicate the location of our local [`azure-sdk-for-java`][azure_sdk_for_java] clone with the flag `--azure-libraries-for-java-folder`. Your output folder would be relative to `azure-libraries-for-java-folder`, the location of which you would pass on the command line. I.e., your `output-folder` would look like `{azure-libraries-for-java-folder}/pets`.
|
||||
|
||||
2. Namespace: We want our Python namespace to be `azure.pets`, while we want our Java namespace to be `com.microsoft.azure.pets`. We want different namespaces based off of whether we're generating `v1` or `v2` as well.
|
||||
3. For Python, we also want to specify the name of our Python package with flag `package-name`
|
||||
4. Finally, for Java, we would like our library to be `fluent`
|
||||
|
||||
Let's put all of this information into our Python readme, `readme.python.md`:
|
||||
````
|
||||
# Python
|
||||
|
||||
These settings apply only when `--python` is specified on the command line.
|
||||
|
||||
``` yaml
|
||||
package-name: azure-pets
|
||||
```
|
||||
|
||||
## Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
namespace: azure.pets.v1
|
||||
output-folder: python/pets/azure-pets/azure/pets/v1
|
||||
```
|
||||
|
||||
## Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
namespace: azure.pets.v2
|
||||
output-folder: python/pets/azure-pets/azure/pets/v2
|
||||
```
|
||||
````
|
||||
|
||||
Similarly, we have our Java readme, `readme.java.md`:
|
||||
````
|
||||
# Java
|
||||
|
||||
These settings apply only when `--java` is specified on the command line.
|
||||
|
||||
``` yaml
|
||||
fluent: true
|
||||
```
|
||||
|
||||
## Tag: v1
|
||||
|
||||
These settings apply only when `--tag=v1` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v1'
|
||||
namespace: com.microsoft.azure.pets.v1
|
||||
output-folder: java/pets/v1
|
||||
```
|
||||
|
||||
## Tag: v2
|
||||
|
||||
These settings apply only when `--tag=v2` is specified on the command line.
|
||||
|
||||
```yaml $(tag) == 'v2'
|
||||
namespace: azure.pets.v2
|
||||
output-folder: java/pets/v2
|
||||
```
|
||||
````
|
||||
|
||||
Now, when generating `v2` code in Python, our command line looks like
|
||||
```
|
||||
autorest readme.md --python
|
||||
```
|
||||
while our Java command looks like
|
||||
```
|
||||
autorest readme.md --java
|
||||
```
|
||||
If we want to generate `v1` code in either language, all that's needed is to tack `--tag=v1` on the command line.
|
||||
|
||||
## Generating Management Plane Code
|
||||
|
||||
There are a couple of steps that are more [management-plane](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/control-plane-and-data-plane#control-plane) specific, which this section will go into.
|
||||
|
||||
The biggest thing to keep in mind when generating management plane code is using the flag `--azure-arm`. This tells the language generators you want management plane code. Since management plane code is more standardized, we are able to generate more specialized code. Setting this `azure-arm` flag also has implications for other flags (i.e., it forces `head-as-boolean` to be true). See our [flag index][flags] for more information.
|
||||
|
||||
The OpenAPI definitions for management plane code also live in the `resource-manager` folder for services in the [azure-rest-api-specs][azure_rest_api_specs] repo (see here the location of [management storage][mgmt_storage]). You will need to also have your `readme.md` on this level (complete with language-specific readmes if necessary, see the [previous section](#generating-in-multiple-languages "Generating in Multiple Languages") for how to do this.)
|
||||
|
||||
## Generating with Directives
|
||||
|
||||
Directives are used to change the code generated from your OpenAPI definition. For example, if you want to change the name of a parameter in an operation without changing the swagger. See [our directives section](./directives.md) if this is something you're interested in.
|
||||
|
||||
## Generating Multi API Code
|
||||
|
||||
Only Python supports generating multiapi code, see [the Python docs](https://github.com/Azure/autorest.python/blob/autorestv3/docs/generate/readme.md) for how to generate.
|
||||
|
||||
## Index of Flags
|
||||
|
||||
See [here](.flags.md) for a complete index of flags.
|
||||
|
||||
## Generate from Private GitHub Repos
|
||||
|
||||
AutoRest supports generating from private GitHub repositories.
|
||||
There are multiple options:
|
||||
|
||||
1) **Using the `token` query parameter**: Pass the `token` query parameter you get when clicking "Raw" on a file of a private repo, i.e. `https://github.com/<path-on-some-private-repo>/readme.md?token=<token>`.
|
||||
When such a URI is passed to AutoRest, it will automatically reuse that token for subsequent requests (e.g. querying referenced OpenAPI definitions).
|
||||
This is a quick and easy solution if you manually want to run AutoRest against private bits from time to time.
|
||||
2) **Using OAuth**: GitHub allows generating OAuth tokens under `Settings -> Personal access tokens`.
|
||||
Create one with `repo` scope.
|
||||
It can be passed to AutoRest using `--github-auth-token=<token>` or by setting the environment variable `GITHUB_AUTH_TOKEN`.
|
||||
This is the way to go for all scripts and automation.
|
||||
Needless to say, *do not put this token* into scripts directly, use Azure KeyVault or similar.
|
||||
**Note**: If the repository is in an organization it might require the Github Token to be given explicit permission to that organization.(Next to the token Enable SSO > Click Authorize for the relevant organization)
|
||||
|
||||
## I'm Curious: How does AutoRest Actually Generate Code From an OpenAPI Definition?
|
||||
|
||||
See [here][how_autorest]
|
||||
|
||||
|
||||
For language-specific information about generation, please refer to our language-specific documentation:
|
||||
|
||||
- [Python][python]
|
||||
- [Java][java]
|
||||
- [C#][csharp]
|
||||
|
||||
<!-- LINKS -->
|
||||
[flags]: ./flags.md
|
||||
[openapi_docs]: ../openapi/readme.md
|
||||
[pets_swagger]: ../openapi/examples/pets.json
|
||||
[basic_example]: ./examples/basic/readme.md
|
||||
[pets_v2_swagger]: ./openapi/examples/pets.json
|
||||
[tags_readme]: ./examples/tags/readme.md
|
||||
[azure_rest_api_specs]: https://github.com/Azure/azure-rest-api-specs
|
||||
[mgmt_storage]: https://github.com/Azure/azure-rest-api-specs/tree/master/specification/storage/resource-manager
|
||||
[how_autorest]: ./how-autorest-generates-code-from-openapi.md
|
||||
[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/generate
|
||||
[java]: https://github.com/Azure/autorest.java/tree/v4/docs/generate
|
||||
[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/generate
|
||||
[azure_sdk_for_python]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk
|
||||
[azure_sdk_for_java]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 53 KiB |
|
|
@ -14,13 +14,13 @@ The AutoRest CLI is updated like any Node package, via NPM:
|
|||
|
||||
## Core Module
|
||||
|
||||
The AutoRest core module is the real processing hub for AutoRest.
|
||||
The AutoRest core module is the real processing hub for AutoRest.
|
||||
|
||||
The CLI can load any version of the AutoRest Core module by using the command line `--version:[VERSION]` where `[VERSION]` is one of:
|
||||
- a semver version range that matches a published nodejs package `@autorest/core` package.<br>AutoRest v3 defaults to `~3.0.6000` (ie, the latest published `3.0` package above build `6000` )
|
||||
- the specific version of the core module package, which can come from npm or a prerelase build in [github releases](https://github.com/azure/autorest/releases)<br>ie, `--version:3.0.6189`
|
||||
- a folder where the core package has been cloned and compiled. (ie, `c:\work\autorest` )
|
||||
- a URL to a nodejs autorest-core package
|
||||
- a URL to a nodejs autorest-core package
|
||||
|
||||
An AutoRest configuration file can also specify a `version:` that requests a specific core module.<br>
|
||||
This can be overridden on the command line with `--version:`<br>
|
||||
|
|
@ -31,12 +31,12 @@ V2 generators will have their core module version defaulting to the latest v2 co
|
|||
> ---
|
||||
> AutoRest core modules are installed into the user's `$HOME/.autorest` folder.<br>
|
||||
> Multiple instances of the core module can be installed side-by-side<br>
|
||||
>
|
||||
>
|
||||
> The core module runs in-process of the CLI (the module library is acquired and executed in the same process)
|
||||
>
|
||||
> AutoRest v2 core modules are called `@microsoft.azure/autorest-core` <br>
|
||||
> AutoRest v3 core modules are called `@autorest/core`<br>
|
||||
>
|
||||
>
|
||||
>
|
||||
> See the [Managing Versions](#Managing-Versions) section below<br>
|
||||
>
|
||||
|
|
@ -60,15 +60,15 @@ If you want to pin to a specific version of an extension or to load one that is
|
|||
> ---
|
||||
> AutoRest extension modules are installed into the user's `$HOME/.autorest` folder.<br>
|
||||
> Multiple instances of an extension module can be installed side-by-side<br>
|
||||
>
|
||||
>
|
||||
> Extension modules are executed out-of-process (communicating via a JSON-RPC protocol over stdin/out). <br>
|
||||
> They can be written in any language (still must be packaged with npm!)<br>
|
||||
> We have plugins written in typescript, c#, python, java.
|
||||
>
|
||||
>
|
||||
> AutoRest v2 extension modules are generally called `@microsoft.azure/autorest.[LANGUAGE]` <br>
|
||||
>
|
||||
>
|
||||
> AutoRest v2 extension modules are generally called `@microsoft.azure/autorest.[LANGUAGE]` <br>
|
||||
> AutoRest v3 extension modules are called `@autorest/[LANGUAGE]`<br>
|
||||
>
|
||||
>
|
||||
>
|
||||
> See the [Managing Versions](#Managing-Versions) section below<br>
|
||||
>
|
||||
|
|
@ -97,7 +97,7 @@ Showing All Installed Extensions
|
|||
|
||||
You can remove all the AutoRest core modules and extensions by using `--reset`:
|
||||
|
||||
> `autorest --reset`
|
||||
> `autorest --reset`
|
||||
``` text
|
||||
AutoRest code generation utility [version: 3.0.6161; node: v10.15.1, max-memory: 8192 gb]
|
||||
(C) 2018 Microsoft Corporation.
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 98 KiB |
|
|
@ -0,0 +1,53 @@
|
|||
# <img align="center" src="./images/logo.png"> Installing AutoRest
|
||||
|
||||
Installing AutoRest on Windows, MacOS or Linux involves two steps:
|
||||
|
||||
1. __Install [Node.js](https://nodejs.org/en/)__ (12.19.x LTS preferred. May not function with Node < 10.x.)
|
||||
> if you want an easy way to install and update Node, I recommend [NVS - Node Version Switcher](./installing-via-nvs.md) or [NVM - Node Version Manager](./installing-via-nvm.md)
|
||||
|
||||
|
||||
2. __Install AutoRest__ using `npm`
|
||||
|
||||
``` powershell
|
||||
# Depending on your configuration you may need to be elevated or root to run this. (on OSX/Linux use 'sudo' )
|
||||
npm install -g autorest
|
||||
|
||||
# run using command 'autorest' to check if installation worked
|
||||
autorest --help
|
||||
```
|
||||
|
||||
3. To confirm you are using AutoRest V3, and not an older version, run `autorest --help`, and confirm your core version is 3.0 and higher.
|
||||
We strongly recommend version `3.06318` or higher due to bug fixes. For more versioning information, see (./autorest-versioning.md)
|
||||
# <img align="center" src="images/autorestCoreVersion.png">
|
||||
|
||||
4. If you're running into issues running AutoRest, check out our [troubleshooting][troubleshooting] docs
|
||||
|
||||
|
||||
### Updating AutoRest
|
||||
To update AutoRest if you have previous versions installed, please run:
|
||||
|
||||
``` powershell
|
||||
autorest --latest
|
||||
```
|
||||
or
|
||||
```powershell
|
||||
# Removes all other versions and plugins and installs the latest autorest-core
|
||||
autorest --reset
|
||||
```
|
||||
For more information, run `autorest --help`
|
||||
|
||||
|
||||
### Not Recommended: Reverting to AutoRest V2
|
||||
|
||||
If you must fall back to AutoRest V2, run
|
||||
|
||||
``` powershell
|
||||
# install the previous stable package from npm
|
||||
npm install -g autorest@previous
|
||||
|
||||
# run using command 'autorest' to check if installation worked
|
||||
autorest --help
|
||||
```
|
||||
|
||||
<!-- LINKS -->
|
||||
[troubleshooting]: ../troubleshooting.md#module-errors
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
# <img align="center" src="./images/logo.png"> Installing AutoRest
|
||||
|
||||
Installing AutoRest on Windows, MacOS or Linux involves two steps:
|
||||
|
||||
1. __Install [Node.js](https://nodejs.org/en/)__ (12.19.x LTS preferred. May not function with Node < 10.x.)
|
||||
> if you want an easy way to install and update Node, I recommend [NVS - Node Version Switcher](./nodejs/installing-via-nvs.md) or [NVM - Node Version Manager](./nodejs/installing-via-nvm.md)
|
||||
|
||||
|
||||
2. __Install AutoRest__ using `npm`
|
||||
|
||||
``` powershell
|
||||
# Depending on your configuration you may need to be elevated or root to run this. (on OSX/Linux use 'sudo' )
|
||||
npm install -g autorest
|
||||
|
||||
# run using command 'autorest'
|
||||
autorest --help
|
||||
```
|
||||
|
||||
### Updating Autorest core
|
||||
To update AutoRest if you have previous versions installed, please run:
|
||||
|
||||
``` powershell
|
||||
autorest --latest
|
||||
```
|
||||
or
|
||||
```powershell
|
||||
# Removes all other versions and plugins and installs the latest autorest-core
|
||||
autorest --reset
|
||||
```
|
||||
For more information, run `autorest --help`
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# <img align="center" src="./images/logo.png"> Introduction to AutoRest
|
||||
|
||||
The **AutoRest** tool generates client libraries for accessing RESTful web services. Input to *AutoRest* is a spec that describes the REST API using the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) format.
|
||||
Here we go into some of the general terms you'll see when gonig through our documentation and interacting with AutoRests.
|
||||
|
||||
## What is OpenAPI?
|
||||
|
||||
OpenAPI is a specification language used to describe a web service API in terms of its operations and the data types it understands. It was originally conceived as a specification called **Swagger**, so you commonly see these two terms used interchangeably.
|
||||
|
||||
OpenAPI is primarily concerned with describing web services that follow the [Representational State Transfer (REST)][rest] architectural model where operations are exposed via URI paths that accept HTTP verbs like GET, PUT, POST, and DELETE. These URI paths generally refer to “resources” understood by the service where the request and response bodies of most operations contain the details of the resource at that path. For example, a POST request with the body containing the desired state of a resource will create that resource, a PUT request with changes to some properties will update the resource, and a DELETE request will cause the resource to be deleted. OpenAPI provides a schema language which enables this type of API to be described in a machine-readable form, usually encoded in JSON.
|
||||
|
||||
The main [swagger docs][swagger_basic_structure] have a good example for the basic structure. For more information on how to write an OpenAPI definition for your service, feel free to refer to the [main swagger docs][swagger_docs] or [our own documentation][openapi_docs] for more AutoRest-specific information.
|
||||
|
||||
## What is AutoRest?
|
||||
|
||||
AutoRest is a tool that provides a code generation framework for converting OpenAPI 2.0 and 3.0 specifications into client libraries for the services described by those specifications. It was developed by Microsoft around the time the OpenAPI Initiative was formed so that Azure service teams could start producing generated client libraries from new Swagger and OpenAPI 2.0 specifications. There are a few extensions that
|
||||
|
||||
At the core of AutoRest is a flexible pipeline where a series of pre-configured phases transform and merge various OpenAPI input files to produce a “code model” that can be consumed by a language-specific code generator. These code generator extensions will interpret the code model and produce code that aligns with the design guidelines for each language. The generated code for a language will use the corresponding Azure Core implementation so that we can provide configurable behavior for how HTTP requests are made in the generated code.
|
||||
|
||||
# <img align="center" src="./images/autorest-pipeline.png">
|
||||
|
||||
See our [landing page][landing_page] to get started with writing your OpenAPI definitions and generating with AutoRest!
|
||||
|
||||
<!--LINKS-->
|
||||
[rest]: https://en.wikipedia.org/wiki/Representational_state_transfer
|
||||
[swagger_basic_structure]: https://swagger.io/docs/specification/basic-structure/
|
||||
[swagger_docs]: https://swagger.io/docs/
|
||||
[openapi_docs]: ./openapi/readme.md
|
||||
[landing_page]: readme.md
|
||||
|
|
@ -1,131 +0,0 @@
|
|||
# <img align="center" src="./images/logo.png"> Managing AutoRest from the command line
|
||||
|
||||
Once you have AutoRest installed using `npm`, it should be available on the PATH, so you can just run it from anywhere:
|
||||
|
||||
``` powershell
|
||||
# The first time you run it, it will pull in the binaries that are needed to run. (no elevation/root required)
|
||||
> autorest
|
||||
|
||||
AutoRest
|
||||
Downloading https://github.com/Azure/autorest/releases/.../dotnet-win7-x64.1.0.4.zip
|
||||
to c:\users\...\.autorest\frameworks
|
||||
Downloading https://github.com/Azure/autorest/releases/.../autorest-1.0.1-20170223-1007-preview.zip
|
||||
to c:\users\...\.autorest\plugins\autorest\1.0.1-20170223-1007-preview
|
||||
|
||||
```
|
||||
|
||||
You can get some help from the command line:
|
||||
|
||||
``` powershell
|
||||
# Run AutoRest and see the command-line help.
|
||||
> autorest --help
|
||||
|
||||
AutoRest
|
||||
Build Information
|
||||
Bootstrapper : 0.9.10
|
||||
NetCore framework : 1.0.4
|
||||
AutoRest core : 1.0.1-20170223-1007-preview
|
||||
|
||||
Output Verbosity
|
||||
--verbose show verbose output information
|
||||
--debug show internal debug information
|
||||
--quiet suppress output
|
||||
|
||||
Versions
|
||||
--list-installed show all installed versions of AutoRest tools
|
||||
--list-available=nn lists the last nn releases available from github
|
||||
(defaults to 10)
|
||||
|
||||
Installation
|
||||
--version=version uses version of AutoRest, installing if necessary.
|
||||
for version you can
|
||||
use a version label (see --list-available) or
|
||||
latest - get latest nightly build
|
||||
latest-release - get latest release version
|
||||
--reset remove all installed versions of AutoRest tools
|
||||
and install the latest (override with --version)
|
||||
|
||||
```
|
||||
|
||||
You can use any version of AutoRest by asking for it on the command-line. If it's not installed, AutoRest will install it first:
|
||||
|
||||
``` powershell
|
||||
# Use the latest nightly or preview version:
|
||||
> autorest --version=latest <...args>
|
||||
|
||||
# Use the latest 'release' version :
|
||||
> autorest --version=latest-release <...args>
|
||||
|
||||
# Use a specific version
|
||||
> autorest --version=1.0.1-20170223-1007-preview <...args>
|
||||
```
|
||||
|
||||
You can see what versions of AutoRest that are available to install:
|
||||
|
||||
``` powershell
|
||||
# show available versions
|
||||
> autorest --list-available
|
||||
|
||||
AutoRest
|
||||
Build Information
|
||||
Bootstrapper : 0.9.10
|
||||
NetCore framework : 1.0.4
|
||||
AutoRest core : 1.0.1-20170223-1007-preview
|
||||
|
||||
Output Verbosity
|
||||
|
||||
--verbose show verbose output information
|
||||
--debug show internal debug information
|
||||
--quiet suppress output
|
||||
|
||||
Versions
|
||||
|
||||
--list-installed show all installed versions of AutoRest tools
|
||||
--list-available=nn lists the last nn releases available from github
|
||||
(defaults to 10)
|
||||
|
||||
Installation
|
||||
|
||||
--version=version uses version of AutoRest, installing if necessary.
|
||||
for version you can
|
||||
use a version label (see --list-available) or
|
||||
latest - get latest nightly build
|
||||
latest-release - get latest release version
|
||||
--reset remove all installed versions of AutoRest tools
|
||||
and install the latest (override with --version)
|
||||
|
||||
Last 10 releases available online:
|
||||
|
||||
1.0.1-20170223-1007-preview
|
||||
1.0.1-20170222-1520-preview
|
||||
```
|
||||
|
||||
You can also see what's installed locally:
|
||||
|
||||
``` powershell
|
||||
# look what is installed already
|
||||
autorest --list-installed
|
||||
AutoRest
|
||||
Build Information
|
||||
Bootstrapper : 0.9.10 # current npm package version
|
||||
NetCore framework : 1.0.4 # current version of the .NET Core framework
|
||||
AutoRest core : 1.0.1-20170223-1007-preview # current version of the AutoRest tool itself.
|
||||
|
||||
Installed versions of AutoRest :
|
||||
|
||||
1.0.1-20170223-1007-preview # list of all the versions installed.
|
||||
```
|
||||
|
||||
If you want to remove all versions of AutoRest and install the just latest version
|
||||
|
||||
``` powershell
|
||||
# Remove all binaries for AutoRest
|
||||
> autorest --reset <...args>
|
||||
|
||||
AutoRest
|
||||
Downloading https://github.com/Azure/autorest/releases/.../dotnet-win7-x64.1.0.4.zip
|
||||
to ~\.autorest\frameworks
|
||||
Downloading https://github.com/Azure/autorest/releases/.../autorest-1.0.1-20170223-1007-preview.zip
|
||||
to ~\.autorest\plugins\autorest\1.0.1-20170223-1007-preview
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
# <img align="center" src="./images/logo.png"> Migrating from AutoRest V2 to V3
|
||||
|
||||
## General Guidance
|
||||
First, make sure when generating you are using AutoRest V3. Follow the steps in [our installation section][install] for information on upgrading
|
||||
and confirming your new AutoRest version.
|
||||
|
||||
## New Features
|
||||
|
||||
### OpenAPI3 support!
|
||||
|
||||
AutoRest 3.0 finally supports OpenAPI3 files as an input format, with the following caveats:
|
||||
|
||||
- existing AutoRest v2 generators may not support all features from OpenAPI3. (see next section)
|
||||
- `anyOf`, `oneOf` are not currently supported
|
||||
- other OpenAPI3 specific features may not be entirely supported.
|
||||
|
||||
### Generators
|
||||
|
||||
A new set of language generator plugins are being written that adopt the lighter-weight patterns for Azure Core libraries.<br>
|
||||
Existing V2 generators will default to processing with the AutoRest 2 pipeline. <br>
|
||||
See the language generator flags [here][language_flags]
|
||||
|
||||
### Generate More Idiomatic SDKs
|
||||
|
||||
Support for track 2 SDKs that follow the guidelines listed [here][guidelines]
|
||||
|
||||
|
||||
For language-specific information about migration and changes, please refer to our language-specific documentation:
|
||||
|
||||
- [Python][python]
|
||||
- [Java][java]
|
||||
- [C#][csharp]
|
||||
- [Typescript][typescript]
|
||||
|
||||
|
||||
<!-- LINKS -->
|
||||
[install]: ../install/readme.md
|
||||
[language_flags]: generate/readme.md#language-flags
|
||||
[guidelines]: https://azure.github.io/azure-sdk/general_introduction.html
|
||||
[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/migrate
|
||||
[java]: https://github.com/Azure/autorest.java/tree/v4/docs/migrate
|
||||
[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/migrate
|
||||
[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/migrate
|
||||
|
|
@ -0,0 +1,136 @@
|
|||
{
|
||||
"swagger": "3.0",
|
||||
"info": {
|
||||
"title": "Pet Client",
|
||||
"description": "Example service client that also manages pets"
|
||||
},
|
||||
"host": "localhost:3000",
|
||||
"schemes": [
|
||||
"http"
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"paths": {
|
||||
"/pets": {
|
||||
"get": {
|
||||
"operationId": "getDog",
|
||||
"description": "Get a dog",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "A 200 OK Dog",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Dog"
|
||||
}
|
||||
},
|
||||
"default": {
|
||||
"description": "Unexpected error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"put": {
|
||||
"operationId": "putCat",
|
||||
"description": "Put a cat onto our servers",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "cat",
|
||||
"in": "body",
|
||||
"description": "Cat",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Cat"
|
||||
},
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Received correct cat",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"operationId": "postKitten",
|
||||
"description": "Post a kitten onto our servers",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "kitten",
|
||||
"in": "body",
|
||||
"description": "Kitten",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Kitten"
|
||||
},
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Received correct kitten",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"Error": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Dog": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"name"
|
||||
],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "The dog's name"
|
||||
},
|
||||
"wagsTailWhenHappy": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the dog wags their tail when happy"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Cat": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"likesMilk": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Kitten": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/Cat"
|
||||
}
|
||||
],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"eatsMiceYet": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
---
|
||||
swagger: '3.0'
|
||||
info:
|
||||
title: Pet Client
|
||||
description: Example service client that also manages pets
|
||||
host: localhost:3000
|
||||
schemes:
|
||||
- http
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
paths:
|
||||
"/pets":
|
||||
get:
|
||||
operationId: getDog
|
||||
description: Get a dog
|
||||
responses:
|
||||
'200':
|
||||
description: A 200 OK Dog
|
||||
schema:
|
||||
"$ref": "#/definitions/Dog"
|
||||
default:
|
||||
description: Unexpected error
|
||||
schema:
|
||||
"$ref": "#/definitions/Error"
|
||||
put:
|
||||
operationId: putCat
|
||||
description: Put a cat onto our servers
|
||||
parameters:
|
||||
- name: cat
|
||||
in: body
|
||||
description: Cat
|
||||
schema:
|
||||
"$ref": "#/definitions/Cat"
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
description: Received correct cat
|
||||
schema:
|
||||
type: string
|
||||
post:
|
||||
operationId: postKitten
|
||||
description: Post a kitten onto our servers
|
||||
parameters:
|
||||
- name: kitten
|
||||
in: body
|
||||
description: Kitten
|
||||
schema:
|
||||
"$ref": "#/definitions/Kitten"
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
description: Received correct kitten
|
||||
schema:
|
||||
type: string
|
||||
definitions:
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
status:
|
||||
type: integer
|
||||
format: int32
|
||||
message:
|
||||
type: string
|
||||
Dog:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: The dog's name
|
||||
wagsTailWhenHappy:
|
||||
type: boolean
|
||||
description: Whether the dog wags their tail when happy
|
||||
Cat:
|
||||
type: object
|
||||
properties:
|
||||
likesMilk:
|
||||
type: boolean
|
||||
Kitten:
|
||||
allOf:
|
||||
- "$ref": "#/definitions/Cat"
|
||||
type: object
|
||||
properties:
|
||||
eatsMiceYet:
|
||||
type: boolean
|
||||
|
|
@ -0,0 +1,159 @@
|
|||
{
|
||||
"swagger": "3.0",
|
||||
"info": {
|
||||
"title": "Pet Client",
|
||||
"description": "Example service client that also manages pets"
|
||||
},
|
||||
"host": "localhost:3000",
|
||||
"schemes": [
|
||||
"http"
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"paths": {
|
||||
"/pets": {
|
||||
"get": {
|
||||
"operationId": "getDog",
|
||||
"description": "Get a dog",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "A 200 OK Dog",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Dog"
|
||||
}
|
||||
},
|
||||
"default": {
|
||||
"description": "Unexpected error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"put": {
|
||||
"operationId": "putCat",
|
||||
"description": "Put a cat onto our servers",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "cat",
|
||||
"in": "body",
|
||||
"description": "Cat",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Cat"
|
||||
},
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Received correct cat",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"operationId": "postKitten",
|
||||
"description": "Post a kitten onto our servers",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "kitten",
|
||||
"in": "body",
|
||||
"description": "Kitten",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Kitten"
|
||||
},
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Received correct kitten",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"dogs/": {
|
||||
"get": {
|
||||
"operationId": "listDogs",
|
||||
"description": "Get a list of dog. Added in version 2 of this swagger.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "A 200 OK Dog list",
|
||||
"schema": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/Dog"
|
||||
}
|
||||
}
|
||||
},
|
||||
"default": {
|
||||
"description": "Unexpected error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"Error": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Dog": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"name"
|
||||
],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "The dog's name"
|
||||
},
|
||||
"wagsTailWhenHappy": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the dog wags their tail when happy"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Cat": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"likesMilk": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Kitten": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/Cat"
|
||||
}
|
||||
],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"eatsMiceYet": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
# <img align="center" src="../images/logo.png"> Writing OpenAPI Definitions for AutoRest
|
||||
|
||||
|
||||
- Main OpenAPI docs [here][swagger]
|
||||
- See AutoRest specific extensions [here][extensions]
|
||||
- See our OpenAPI definition rules [here][rules]
|
||||
- Generally swaggers are kept in [this][azure_rest_api_specs] repo
|
||||
|
||||
<!-- LINKS -->
|
||||
[swagger]: https://swagger.io/docs/
|
||||
[extensions]: ../extensions/readme.md
|
||||
[rules]: https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/openapi-authoring-automated-guidelines.md
|
||||
[azure_rest_api_specs]: https://github.com/Azure/azure-rest-api-specs
|
||||
Различия файлов скрыты, потому что одна или несколько строк слишком длинны
|
|
@ -1,37 +1,41 @@
|
|||
# AutoRest Documentation
|
||||
|
||||
1. Installing AutoRest.
|
||||
- You can [install AutoRest](./installing-autorest.md) on Windows, Mac, or Linux.
|
||||
1. Introduction
|
||||
- Get an [introduction][introduction] to the fundamental concepts of AutoRest
|
||||
|
||||
1. [Defining Clients With OpenAPI](developer/guide/how-autorest-generates-code-from-swagger.md)
|
||||
- AutoRest-specific [OpenAPI Extensions](extensions/readme.md)
|
||||
2. Installing AutoRest
|
||||
- You can [install AutoRest][install] on Windows, Mac, or Linux.
|
||||
|
||||
2. Generating Clients
|
||||
- [Command Line Interface](user/command-line-interface.md) - using AutoRest from the command line.
|
||||
- using AutoRest in Visual Studio.
|
||||
3. Defining Clients with OpenAPI
|
||||
- Learn [how to define your REST API][openapi] with OpenAPI
|
||||
|
||||
3. Using a Generated Client (C#) - overview of the generated code and extensibility points.
|
||||
- [Project Setup](client/proj-setup.md)
|
||||
- [Initialization](client/init.md)
|
||||
- [Operations](client/ops.md)
|
||||
- [Authentication](client/auth.md)
|
||||
- [Error Handling](client/error.md)
|
||||
- [Tracing](client/tracing.md)
|
||||
- [Automatic Retries](client/retry.md)
|
||||
4. Generating Clients with AutoRest
|
||||
- How do I generate code? See [here][generate]
|
||||
|
||||
4. AutoRest Architecture
|
||||
- Overview
|
||||
- Code Generators
|
||||
- Modelers
|
||||
5. Using Your Generated Client
|
||||
- How do I [use my client][client] now that I've generated it?
|
||||
|
||||
5. [Building AutoRest](developer/guide/building-code.md)
|
||||
6. Migrating from AutoRest 2.0 to 3.0
|
||||
- I have old generated code using the previous version of AutoRest. How do I [upgrade][migrate] my generation and use my new code?
|
||||
|
||||
6. [Writing Tests](developer/guide/writing-tests.md)
|
||||
7. Developing with AutoRest
|
||||
- How do I generate or contribute to AutoRest in [dev mode][dev]?
|
||||
|
||||
6. [Writing OpenAPI Validation Rules](https://github.com/Azure/azure-openapi-validator/blob/master/docs/developer/authoring-new-validation-rules.md)
|
||||
8. `Powershell` documentation
|
||||
- [How][powershell] do I use AutoRest to build `Powershell` cmdlets?
|
||||
|
||||
7. Contributing to the code
|
||||
9. [FAQ][faq]
|
||||
|
||||
8. OpenAPI (formerly 'Swagger') specifications:
|
||||
- [OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (f.k.a. Swagger 2.0)
|
||||
- [OpenAPI Spec 3.0.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
|
||||
10. [Troubleshooting][troubleshooting]
|
||||
|
||||
<!-- LINKS -->
|
||||
[introduction]: ./introduction.md
|
||||
[install]: ./install/readme.md
|
||||
[openapi]: ./openapi/readme.md
|
||||
[generate]: ./generate/readme.md
|
||||
[client]: ./client/readme.md
|
||||
[migrate]: ./migrate/readme.md
|
||||
[dev]: ./developer/readme.md
|
||||
[powershell]: ./powershell/readme.md
|
||||
[faq]: ./faq.md
|
||||
[troubleshooting]: ./troubleshooting.md
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
# AutoRest repositories and packages
|
||||
|
||||
| Repository | Package | PRs | Issues |
|
||||
| ---------- | -:| -:| -:|
|
||||
| [AutoRest bootstrapper](https://github.com/Azure/autorest/tree/master/autorest) | [](https://www.npmjs.com/package/autorest )<br>  |
|
||||
| [AutoRest core](https://github.com/Azure/autorest/tree/master/core) | [](https://www.npmjs.com/package/@microsoft.azure/autorest-core)<br>  | [](https://github.com/Azure/autorest/pulls) | [](https://github.com/Azure/autorest/issues) |
|
||||
|
||||
## Code Generation
|
||||
|
||||
| Repository | | Package | PRs | Issues | Activation |
|
||||
| ---------- |-| -:| -:| -:|:- |
|
||||
| [autorest.azureresourceschema](https://github.com/Azure/autorest.azureresourceschema) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_json.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.azureresourceschema)<br>  | [](https://github.com/Azure/autorest.azureresourceschema/pulls) | [](https://github.com/Azure/autorest.azureresourceschema/issues) | `--azureresourceschema` |
|
||||
| [autorest.csharp](https://github.com/Azure/autorest.csharp) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_csharp.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.csharp )<br>  | [](https://github.com/Azure/autorest.csharp/pulls) | [](https://github.com/Azure/autorest.csharp/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3Ac%23) | `--csharp` |
|
||||
| [autorest.go](https://github.com/Azure/autorest.go) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_go.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.go )<br>  | [](https://github.com/Azure/autorest.go/pulls) | [](https://github.com/Azure/autorest.go/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3Ago) | `--go` |
|
||||
| [autorest.java](https://github.com/Azure/autorest.java) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_java.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.java )<br>  | [](https://github.com/Azure/autorest.java/pulls) | [](https://github.com/Azure/autorest.java/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3Ajava) | `--java` |
|
||||
| [autorest.nodejs](https://github.com/Azure/autorest.nodejs) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_js.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.nodejs )<br>  | [](https://github.com/Azure/autorest.nodejs/pulls) | [](https://github.com/Azure/autorest.nodejs/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3Anodejs) | `--nodejs` |
|
||||
| [autorest.php](https://github.com/Azure/autorest.php) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_php.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.php )<br>  | [](https://github.com/Azure/autorest.php/pulls) | [](https://github.com/Azure/autorest.php/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3APHP) | `--php` |
|
||||
| [autorest.python](https://github.com/Azure/autorest.python) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_python.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.python )<br>  | [](https://github.com/Azure/autorest.python/pulls) | [](https://github.com/Azure/autorest.python/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3Apython) | `--python` |
|
||||
| [autorest.ruby](https://github.com/Azure/autorest.ruby) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_ruby.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.ruby )<br>  | [](https://github.com/Azure/autorest.ruby/pulls) | [](https://github.com/Azure/autorest.ruby/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3Aruby) | `--ruby` |
|
||||
| [autorest.typescript](https://github.com/Azure/autorest.typescript) | <img width="32px" src="https://raw.githubusercontent.com/vscode-icons/vscode-icons/master/icons/file_type_typescript.svg?sanitize=true"> | [](https://www.npmjs.com/package/@microsoft.azure/autorest.typescript )<br>  | [](https://github.com/Azure/autorest.typescript/pulls) | [](https://github.com/Azure/autorest.typescript/issues ) | `--typescript` |
|
||||
| [autorest.modeler](https://github.com/Azure/autorest.modeler) | | [](https://www.npmjs.com/package/@microsoft.azure/autorest.modeler )<br>  | [](https://github.com/Azure/autorest.modeler/pulls) | [](https://github.com/Azure/autorest.modeler/issues )<br> [](https://github.com/Azure/autorest/issues?q=is%3Aopen+is%3Aissue+label%3Amodeler) | |
|
||||
| [autorest.common](https://github.com/Azure/autorest.common) | | [](https://www.nuget.org/packages/Microsoft.autorest.common) | [](https://github.com/Azure/autorest.common/pulls) | [](https://github.com/Azure/autorest.common/issues ) | |
|
||||
| [autorest.testserver](https://github.com/Azure/autorest.testserver) | | [](https://www.npmjs.com/package/@microsoft.azure/autorest.testserver) | [](https://github.com/Azure/autorest.testserver/pulls) | [](https://github.com/Azure/autorest.testserver/issues ) | |
|
||||
|
||||
## Validation
|
||||
|
||||
| Repository | Package | PRs | Issues | Activation |
|
||||
| ---------- | -:| -:| -:|:- |
|
||||
| [classic-openapi-validator](https://github.com/Azure/azure-openapi-validator/tree/master/src/dotnet) | [](https://www.npmjs.com/package/@microsoft.azure/classic-openapi-validator )<br>  | | | `--azure-validator` |
|
||||
| [openapi-validator](https://github.com/Azure/azure-openapi-validator/tree/master/src/typescript) | [](https://www.npmjs.com/package/@microsoft.azure/openapi-validator )<br>  | [](https://github.com/Azure/azure-openapi-validator/pulls) | [](https://github.com/Azure/azure-openapi-validator/issues) | `--azure-validator` |
|
||||
| [oav](https://github.com/Azure/oav) | [](https://www.npmjs.com/package/oav) | [](https://github.com/Azure/oav/pulls) | [](https://github.com/Azure/oav/issues) | `--semantic-validator`, `--model-validator` |
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
# <img align="center" src="./images/logo.png"> Troubleshooting
|
||||
|
||||
## Module Errors
|
||||
|
||||
When running into an AutoRest issues actually running the AutoRest program, your first instinct should always to be run `autorest --reset`. This clears you AutoRest temp folders and extensions, and reacquires them on your next call to AutoRest.
|
||||
|
||||
## Generation Errors
|
||||
|
||||
There are two broad kinds of errors you can run into when generating: one kind is thrown earlier in the AutoRest pipeline and has to do with malformed swaggers (see [our main docs][main_docs] for more information). The other kind is thrown by the language generators.
|
||||
|
||||
The general AutoRest errors are thrown like this, and are commonly due to swagger issues.
|
||||
|
||||
```
|
||||
FATAL: Error: Enum types of 'object' and format 'undefined' are not supported. Correct your input (HdiNodeTypes).
|
||||
Error: Plugin modelerfour reported failure.
|
||||
```
|
||||
|
||||
If you're error does not look like this, refer to the docs in our language generators:
|
||||
|
||||
- [Python][python_generation]
|
||||
- [Java][java_generation]
|
||||
- [C#][csharp_generation]
|
||||
- [Typescript][typescript_generation]
|
||||
|
||||
|
||||
Both of these issues should give you enough information to fix the error. If not, please let us know in either the [main repo][autorest_issues], or in the [Python repo][autorest_python_issues]. Also let us know if you believe
|
||||
there are erroneous errors being thrown.
|
||||
|
||||
## Debugging
|
||||
|
||||
We use flags to correspond our debugging process, view our [debugging flags][debugging_flags] to find out which ones would work best for you.
|
||||
|
||||
If you would like to actually debug through a language generator's code, see our language-specific instructions:
|
||||
|
||||
- [Python][python_debug]
|
||||
- [Java][java_debug]
|
||||
- [C#][csharp_debug]
|
||||
- [Typescript][typescript_debug]
|
||||
|
||||
<!-- LINKS -->
|
||||
[main_docs]: https://github.com/Azure/autorest/tree/master/docs/generate/troubleshooting.md
|
||||
[autorest_issues]: https://github.com/Azure/autorest/issues
|
||||
[autorest_python_issues]: https://github.com/Azure/autorest.python/issues
|
||||
[main_debugging]: https://github.com/Azure/autorest/tree/master/docs/generate/troubleshooting.md#debugging
|
||||
[autorest_python_repo]: https://github.com/Azure/autorest.python/tree/autorestv3
|
||||
[debugging_flags]: generate/flags.md#debugging-flags
|
||||
[python_generation]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/troubleshooting.md#generation-errors
|
||||
[java_generation]: https://github.com/Azure/autorest.java/tree/v4/docs/troubleshooting.md#generation-errors
|
||||
[csharp_generation]: https://github.com/Azure/autorest.csharp/tree/v3/docs/troubleshooting.md#generation-errors
|
||||
[typescript_generation]: https://github.com/Azure/autorest.typescript/tree/v6/docs/troubleshooting.md#generation-errors
|
||||
[python_debug]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/troubleshooting.md#debugging
|
||||
[java_debug]: https://github.com/Azure/autorest.java/tree/v4/docs/troubleshooting.md#debugging
|
||||
[csharp_debug]: https://github.com/Azure/autorest.csharp/tree/v3/docs/troubleshooting.md#debugging
|
||||
[typescript_debug]: https://github.com/Azure/autorest.typescript/tree/v6/docs/troubleshooting.md#debugging
|
||||
84
readme.md
84
readme.md
|
|
@ -2,93 +2,17 @@
|
|||
|
||||
The **AutoRest** tool generates client libraries for accessing RESTful web services. Input to *AutoRest* is a spec that describes the REST API using the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) format.
|
||||
|
||||
<!-- 1) returns SVGs now which aren't rendered by GitHub 2) seems to be awfully unresponsive and unreliable lately
|
||||
[](http://issuestats.com/github/Azure/autorest)
|
||||
[](http://issuestats.com/github/Azure/autorest)
|
||||
-->
|
||||
|
||||
## Support Policy
|
||||
|
||||
AutoRest is an open source tool -- if you need assistance, first check the documentation. If you find a bug or need some help, feel free to submit an [issue](https://github.com/Azure/autorest/issues)
|
||||
|
||||
## Getting Started using AutoRest 
|
||||
|
||||
Start by reading the documentation for using AutoRest:
|
||||
|
||||
- [Installing AutoRest](./docs/installing-autorest.md) - Shows how to install AutoRest.
|
||||
- [Understanding AutoRest Versions and Extensions](./docs/autorest-versioning.md) - AutoRest core and extension versioning
|
||||
- [Managing AutoRest](./docs/managing-autorest.md) - shows how to get new updates to AutoRest and choose which version to use for code generation.
|
||||
- [Generating a Client using AutoRest](./docs/examples/generating-a-client.md) - shows simple command line usage for generating a client library.
|
||||
- [Command Line Interface Documentation](./docs/user/command-line-interface.md) - explains common command line arguments.
|
||||
- [Examples](./Samples) - full, walkthrough-style scenarios for using AutoRest.
|
||||
- [Recent Updates](./changelog.md) - notes on recent updates .
|
||||
|
||||
## New! AutoRest Version 3.0
|
||||
|
||||
AutoRest 3.0 introduces a large number of internal changes to support new scenarios.
|
||||
|
||||
## Features
|
||||
|
||||
### OpenAPI3 support!
|
||||
|
||||
AutoRest 3.0 finally supports OpenAPI3 files as an input format, with the following caveats:
|
||||
|
||||
- existing AutoRest v2 generators may not support all features from OpenAPI3. (see next section)
|
||||
- `anyOf`, `oneOf` are not currently supported
|
||||
- other OpenAPI3 specific features may not be entirely supported.
|
||||
|
||||
### Generators
|
||||
|
||||
A new set of language generator plugins are being written that adopt the lighter-weight patterns for Azure Core libraries.<br>
|
||||
Existing V2 generators will default to processing with the AutoRest 2 pipeline. <br>
|
||||
If you want to force it to use the v3 (to get support for OpenAPI3 ) add `--v3` to the command line:
|
||||
> `autorest --v3 --csharp ...`
|
||||
|
||||
| Generator | Command | Notes |
|
||||
|----|---|---|
|
||||
|PowerShell| `autorest --powershell ...` |Fully V3 Supported - use to generate powershell modules |
|
||||
|CSharp|`autorest --csharp ...` |v2 generator, may use OpenAPI3 with `--v3` switch (may be some differences) - v3 generator in progress |
|
||||
|Python|`autorest --python ...` |v2 generator, may use OpenAPI3 with `--v3` switch (may be some differences) - v3 generator in progress|
|
||||
|Java|`autorest --java ...` |v2 generator, may use OpenAPI3 with `--v3` switch (may be some differences) - v3 generator in progress |
|
||||
|TypeScript|`autorest --typescript ...` |v2 generator, may use OpenAPI3 with `--v3` switch (may be some differences) - v3 generator in progress |
|
||||
|Go|`autorest --go ...` |v2 generator, may use OpenAPI3 with `--v3` switch (may be some differences) - v3 generator in progress |
|
||||
|Ruby|`autorest --ruby ...` |v2 generator - does not support v3 feature, no OpenAPI3 support |
|
||||
|
||||
#### New V3 Pipeline
|
||||
|
||||
In AutoRest v3, the pipeline has been drastically rebuilt, which allows support for:
|
||||
|
||||
- OpenAPI3 inputs
|
||||
- Supporting merging multiple API versions
|
||||
- Model Deduplication and Subset reduction across multiple API versions
|
||||
- Azure Profile support (v3 generator required)
|
||||
|
||||
Some related information:
|
||||
|
||||
- [Validation Rules & Linting](https://github.com/Azure/azure-openapi-validator/blob/master/docs/readme.md) - about the validation rules in AutoRest
|
||||
- [Client Runtimes](./docs/developer/architecture/Autorest-and-Clientruntimes.md) - information about the client runtimes required for using code generated by AutoRest
|
||||
<!-- - [Developer Guide](./docs/developer/guide/) - Notes on developing with AutoRest -->
|
||||
|
||||
### Supported Platforms
|
||||
|
||||
While AutoRest itself runs on NodeJS, some generators use the .NET Core 2.0 runtime, which is the most limiting factor.
|
||||
See [dotnet/core/release-notes/2.0/2.0-supported-os.md](https://github.com/dotnet/core/blob/master/release-notes/2.0/2.0-supported-os.md) for a list of supported platforms.
|
||||
|
||||
#### Preview features
|
||||
|
||||
##### Server-side code generation for Azure Functions
|
||||
|
||||
You can now use the new Azure Functions generators to generate Function App skeleton projects from OpenAPI specs. To try it out, use one of the following generators:
|
||||
|
||||
| Generator | Command | Notes |
|
||||
|----|---|---|
|
||||
|CSharp|`autorest --azure-functions-csharp ...` | Built on `--v3` work done for autorest.csharp. Supports both v2 and v3. More information on usage is available at [autorest.azure-functions-csharp](https://github.com/Azure/autorest.azure-functions-csharp) |
|
||||
|Python|`autorest --azure-functions-python ...` | Built on `--v3` work done for autorest.python. More information on usage is available at [autorest.azure-functions-python](https://github.com/Azure/autorest.azure-functions-python) |
|
||||
|Java|`autorest --azure-functions-java ...` | Built on `--v3` work done for autorest.java. More information on usage is available at [autorest.azure-functions-java](https://github.com/Azure/autorest.azure-functions-java) |
|
||||
|TypeScript|`autorest --azure-functions-typescript ...` | Built on `--v3` work done for autorest.typescript. More information on usage is available at [autorest.azure-functions-typescript](https://github.com/Azure/autorest.azure-functions-typescript) |
|
||||
|
||||
---
|
||||
View our [docs readme][docs_readme] as a starting point to find both general information and language-generator specific information
|
||||
|
||||
### Code of Conduct
|
||||
|
||||
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 [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
|
||||
<!--LINKS-->
|
||||
[docs_readme]: docs/readme.md
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче