Merge pull request #825 from Azure/docs

docs

docs/client/initializing.md

@@ -0,0 +1,47 @@
+# <img align="center" src="../images/logo.png">  Initializing Your Typescript Client
+
+The first step to using your generated client in code is to import and initialize your client. Our SDKs are modelled such
+that the client is the main point of access to the generated code.
+
+## Importing Your Client
+
+You import your client from the package specified when generating (under flag `--package-name`). For the sake of this example,
+let's say the namespace is `@azure/pets`. Your client's name is detailed in the swagger, (TODO link to swagger docs), and let's say
+ours is called `PetsClient`.
+
+Putting this together, we import our client like so:
+
+```js
+import { PetsClient } from "@azure/pets";
+```
+
+## Initializing and Authenticating Your Client
+
+Next, on to initialization. Your constructor can take any number of parameters. For the most basic client with no parameters, you can initialize your client like so:
+
+```js
+import { PetsClient } from "@azure/pets";
+
+const client: PetsClient = new PetsClient();
+```
+
+If you generate with flag `--add-credentials`, your client wil be generated with an [Azure Active Directory (AAD) token credential][aad_authentication]. We always recommend
+using a [credential type][identity_credentials] obtained from the [`@azure/identity`][azure_identity_library] library for AAD authentication. For this example,
+we use the most common [`DefaultAzureCredential`][default_azure_credential].
+
+As an installation note, the [`@azure/identity`][azure_identity_library] library is not a requirement in our generated `package.json` file, so you would need to install this library separately.
+
+```js
+import { DefaultAzureCredential } from "@azure/identity";
+import { PetsClient } from "@azure/pets";
+
+const client: PetsClient = new PetsClient(new DefaultAzureCredential());
+```
+
+<!-- LINKS -->
+[azure_identity_library]: https://www.npmjs.com/package/@azure/identity
+[flag_index]: https://github.com/Azure/autorest/tree/master/docs/generate/flags.md
+[aad_authentication]: https://docs.microsoft.com/en-us/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-azure-active-directory
+[identity_credentials]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/identity/identity#credential-classes
+[default_azure_credential]: https://docs.microsoft.com/en-us/javascript/api/@azure/identity/defaultazurecredential?view=azure-node-latest
+[azure_key_credential]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python

docs/client/models.md

@@ -0,0 +1,18 @@
+# <img align="center" src="../images/logo.png">  Accessing Models and Enums
+
+## General
+
+Models and enums are generated in the `models` module. So, say you are using package `@azure/pets`. To access model `Dog`, you would use the following code
+snippet
+
+```js
+import { Dog } from "@azure/pets";
+```
+
+Enums are also listed in the `models` namespace, so say you have enum class `DogTypes`. To access the `Dalmation` enum, your code would look like
+
+```js
+import { DogTypes } from "@azure/pets";
+
+const dogType: str = DogTypes.Dalmation;
+```

docs/client/operations.md

@@ -0,0 +1,92 @@
+# <img align="center" src="../images/logo.png">  Calling Operations with Your Typescript Client
+
+AutoRest provides asynchronous method overloads for each service operation.
+Depending on your swagger definition, operations can be accessed through operation groups (TODO: link to swagger docs) on the client,
+or directly on the client.
+
+## Operation Group vs No Operation Group
+
+If your swagger defines an operation group for your operation (for example, in [this][operation_group_example] swagger, the operation `list`
+is part of operation group `application`), you would access the operation through `client.application.list()`.
+
+If there's no operation group, as in [this][mixin_example] case, you would access the operation directly from the client
+itself, i.e. `client.getDog()`.
+
+## Regular Operations
+
+When calling our async operations, we go through our client
+
+```js
+import { DefaultAzureCredential } from "@azure/identity";
+import { PetsClient } from "@azure/pets";
+
+const client: PetsClient = new PetsClient(new DefaultAzureCredential());
+const dog = await client.getDog();
+```
+
+## Long Running Operations
+
+Long-running operations are operations which consist of an initial request sent to the service to start an operation, followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has succeeded, to get the result.
+
+In concurrence with our [typescript guidelines][poller_guidelines], all of our long running operations are prefixed with `begin`, to signify the starting of the long running operation.
+
+For our example, we will use the long running operation generated from [this][example_swagger] swagger. Let's say we generated this swagger with package name `@azure/lro`.
+
+By default, our async long running operations return an [`Poller`][poller] polling object, though there [are ways][custom_poller] of changing this. Calling `.pollUntilDone()`
+on the poller will wait until the long running operation finishes then return the final result.
+
+```js
+import { DefaultAzureCredential } from "@azure/identity";
+import { Product, PollingPagingExampleClient } from "@azure/lro";
+
+const client: PollingPagingExampleClient = new PollingPagingExampleClient(new DefaultAzureCredential());
+
+const inputProduct: Product = {
+    id: 1;
+    name: "My Polling example"
+};
+
+const poller = await client.beginBasicPolling(inputProduct);
+const outputProduct = await poller.pollUntilDone();
+```
+
+## Paging Operations
+
+A paging operation pages through lists of data, returning an iterator for the items. Network calls get made when users start iterating through the output, not when the operation
+is initially called.
+
+For our example, we will use the long running operation generated from [this][example_swagger] swagger. Let's say we generated this swagger with package name `@azure/paging`.
+
+By default, our async paging operations return an [`PagedAsyncIterableIterator`][paged_async_iterable_iterator] pager. Since network calls aren't
+made until starting to page, our generated operation is synchronous, and there's no need to wait the initial call to the function. Since network calls are made when iterating,
+we have to do async looping.
+
+```js
+import { DefaultAzureCredential } from "@azure/identity";
+import { PollingPagingExampleClient } from "@azure/paging";
+
+const client: PollingPagingExampleClient = new PollingPagingExampleClient(new DefaultAzureCredential());
+
+const pager = client.basicPaging();
+for await (const product of pager) {
+    console.log(`${product.id}, ${product.name}`);
+}
+```
+
+## Advanced: LRO + paging
+
+We also support generating a long running paging operation. In this case, we return a poller from the operation, and the final result from the poller is
+a pager that pages through the final lists of data.
+
+
+<!-- LINKS -->
+[operation_group_example]: https://github.com/Azure/azure-rest-api-specs/blob/master/specification/batch/data-plane/Microsoft.Batch/stable/2020-09-01.12.0/BatchService.json#L64
+[mixin_example]: https://github.com/Azure/autorest/blob/new_docs/docs/openapi/examples/pets.json#L20
+[pets_swaggger]: https://github.com/Azure/autorest/blob/new_docs/docs/openapi/examples/pets.json
+[initializing]: ./initializing.md
+[poller]:  https://docs.microsoft.com/en-us/javascript/api/@azure/core-lro/poller?view=azure-node-latest
+[custom_poller]: ../generate/directives.md#generate-with-a-custom-poller
+[example_swagger]: ../samples/specification/directives/pollingPaging.json
+[poller_guidelines]: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro
+[custom_pager]: ../generate/directives.md#generate-with-a-custom-pager
+[paged_async_iterable_iterator]: https://docs.microsoft.com/en-us/javascript/api/@azure/core-paging/pagedasynciterableiterator?view=azure-node-latest

docs/client/readme.md

@@ -0,0 +1,17 @@
+# <img align="center" src="../images/logo.png">  Using the Typescript Client
+
+After [generating][generate] your client, this section tells you how to actually use your generated client.
+
+* [Initializing Your Typescript Client][initializing]
+* [Calling Operations with Your Typescript Client][operations]
+* [Accessing Models and Enums][models]
+* [Troubleshooting][troubleshooting]
+* [Tracing][tracing]
+
+<!-- LINKS -->
+[generate]: https://github.com/Azure/autorest/tree/master/docs/generate/readme.md
+[initializing]: ./initializing.md
+[operations]: ./operations.md
+[models]: ./models.md
+[troubleshooting]: ./troubleshooting.md
+[tracing]: ./tracing.md

docs/client/tracing.md

@@ -0,0 +1,84 @@
+# <img align="center" src="../images/logo.png">  Tracing
+
+Our generated code natively [`OpenCensus`][open_census] and [`OpenTelemetry`][open_telemetry]. To do so, generate with flag `--trace` (see our [flag index][flag_index] for more information).
+By default, all libraries log with a NoOpTracer that takes no action. To change this, you have to use setTracer to set a new default Tracer.
+
+To trace, make sure you install [our tracing library][tracing_library]:
+
+```
+npm install @azure/core-tracing
+```
+
+## OpenCensus
+
+Our generated SDKs handle retrieving context for you, so there's no need to pass in any context. Additionally, the
+OpenCensus threading plugin is included when installing this package.
+
+Since there is no explicit context you need to pass, you can create your usual OpenCensus tracer and call the generated SDKs.
+The following example uses the [Zipkin][zipkin] exporter.
+
+```js
+import tracing from "@opencensus/nodejs");
+import { ZipkinTraceExporter } from "@opencensus/exporter-zipkin";
+import {
+  setTracer,
+  OpenCensusTracerWrapper,
+  OpenCensusSpanWrapper
+} from "@azure/core-tracing";
+
+const tracer = tracing.start({ samplingRate: 1 }).tracer;
+
+tracer.registerSpanEventListener(
+  new ZipkinTraceExporter({
+    serviceName: "azure-tracing-sample",
+    bufferTimeout: 2
+  })
+);
+setTracer(new OpenCensusTracerWrapper(tracer));
+tracer.startRootSpan({ name: "root" }, async (rootSpanEx) => {
+  const rootSpan = new OpenCensusSpanWrapper(rootSpanEx);
+  // Call some client library methods and pass rootSpan via tracingOptions.
+  rootSpanEx.end(); // rootSpan.end() should work as well
+});
+```
+
+## OpenTelemetry
+
+First step is to install our [`OpenTelemetry` library][our_open_telemetry_library]:
+
+```bash
+npm install --save @azure/core-tracing
+```
+
+Since there is no explicit context you need to pass, you can create your usual OpenTelemetry tracer and call the generated SDKs.
+The following example uses the [Zipkin][zipkin] exporter.
+```js
+import opentelemetry from "@opentelemetry/core";
+import { BasicTracer, SimpleSpanProcessor } from "@opentelemetry/tracing";
+import { ZipkinExporter } = from "@opentelemetry/exporter-zipkin";
+import { setTracer } from "@azure/core-tracing";
+
+const exporter = new ZipkinExporter({
+  serviceName: "azure-tracing-sample"
+});
+const tracer = new BasicTracer();
+tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+opentelemetry.initGlobalTracer(tracer);
+
+const rootSpan = opentelemetry.getTracer().startSpan("root");
+
+// Call some client library methods and pass rootSpan via tracingOptions.
+
+rootSpan.end();
+exporter.shutdown();
+```
+
+<!-- LINKS -->
+[open_census]: https://opencensus.io/
+[open_telemetry]: https://opentelemetry.io/
+[flag_index]: https://github.com/Azure/autorest/tree/master/docs/generate/flags.md
+[tracing_library]: https://www.npmjs.com/package/@azure/core-tracing
+[azure_monitor]: https://pypi.org/project/opentelemetry-azure-monitor/
+[zipkin]: https://zipkin.io/
+[our_open_telemetry_library]: https://pypi.org/project/azure-core-tracing-opentelemetry/

docs/client/troubleshooting.md

@@ -0,0 +1,32 @@
+# <img align="center" src="../images/logo.png">  Troubleshooting
+
+## Error Handling
+
+Our generated clients raise errors when a service cal returns an undesired error code.
+
+A very basic form of error handling looks like this
+
+```js
+import { DefaultAzureCredential } from "@azure/identity";
+import { PetsClient } from "@azure/pets";
+
+const client: PetsClient = new PetsClient(new DefaultAzureCredential());
+try {
+    const dog = await client.getDog();
+} catch (err) {
+    console.log(err.statusCode);
+}
+```
+
+## Logging
+
+Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`.
+
+```
+export AZURE_LOG_LEVEL=info
+```
+
+For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs][logger-docs]
+
+<!-- LINKS -->
+[logger_docs]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/core/logger

docs/faq.md

@@ -0,0 +1,16 @@
+# <img align="center" src="./images/logo.png">  FAQ
+
+1. What version of AutoRest Typescript should I use?
+
+    CURRENTLY NO AUTOREST TYPESCRIPT ON NPM
+
+    We highly recommend you use the latest AutoRest Typescript version published to [npm][autorest_npm]. The latest version
+    is the default if you use flag `--typescript`, though you may need to run an `autorest --reset` if it seems
+    the latest version is not being grabbed.
+
+    If you *really* want to use an older version of AutoRest Typescript,
+    you can specify the version with the flag `--use`, i.e. `--use=@autorest/[email protected]`.
+
+
+<!-- LINKS -->
+[autorest_npm]: https://www.npmjs.com/package/@autorest/python

docs/migrate/readme.md

@@ -0,0 +1,11 @@
+# <img align="center" src="../images/logo.png">  Migrating to Latest AutoRest
+
+See the [main docs][main_docs] for changes in versioning and flags, this section focuses on how the generated code differs.
+
+## Breaking Changes
+
+TODO
+
+## New Features
+
+TODO

docs/readme.md

@@ -0,0 +1,36 @@
+# AutoRest Typescript Documentation
+
+These documents are Typescript-specific, see [our main docs][main_docs] for more general information
+
+1. Generating Typescript Clients with AutoRest
+    - How do I generate code? Main documents are [here][main_generate], while here are the [typescript-specific docs][typescript_generate]
+
+2. Using Your Generated Typescript Client
+    - How do I [use my Typescript client][typescript_client] now that I've generated it? Main docs are [here][main_client]
+
+3. Migrating from AutoRest 2.0 to 3.0
+    - I have old generated code using the previous version of AutoRest. How do I upgrade my code? Main docs [here][main_migrate], Typescript-specific docs [here][typescript_migrate]
+
+4. Developing with AutoRest
+    - How do I generate or contribute to AutoRest in [dev mode][typescript_dev] Main docs [here][main_dev]
+
+5. Samples
+    - [Sample][sample] readmes and generated code for common scenarios.
+
+6. [FAQ][faq]
+
+7. [Troubleshooting][troubleshooting]
+
+<!-- LINKS -->
+[main_docs]: https://github.com/Azure/autorest/tree/master/docs
+[main_generate]: https://github.com/Azure/autorest/tree/master/docs/generate/readme.md
+[typescript_generate]: ./generate/readme.md
+[typescript_client]: ./client/readme.md
+[main_client]: https://github.com/Azure/autorest/tree/master/docs/generate/client.md
+[main_migrate]: https://github.com/Azure/autorest/tree/master/docs/migrate/readme.md
+[typescript_migrate]: ./migrate/readme.md
+[typescript_dev]: ./developer/readme.md
+[main_dev]: https://github.com/Azure/autorest/tree/master/docs/dev/readme.md
+[sample]: ./samples/readme.md
+[faq]: ./faq.md
+[trobleshooting]: ./troubleshooting.md

docs/samples/readme.md

@@ -0,0 +1,16 @@
+# <img align="center" src="../images/logo.png"> Sample Python Generation
+
+Here are our samples for common generation scenarios
+
+
+| Scenario | README | Generated Code
+|------------------|-------------|-------------
+|Generating most basic | [readme.md][basic_readme] | [generated][basic_generated]
+|Generating [management plane][mgmt] | [readme.md][mgmt_readme] | [generated][mgmt_generated]
+
+<!-- LINKS -->
+[basic_readme]: ./specification/basic/readme.md
+[basic_generated]: ./specification/basic/generated
+[mgmt]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/control-plane-and-data-plane#control-plane
+[mgmt_readme]: ./specification/management/readme.md
+[mgmt_generated]: ./specification/management/generated

docs/samples/specification/basic/readme.md

@@ -0,0 +1,10 @@
+# Sample Basic Generation
+
+### Settings
+
+``` yaml
+input-file: ../../../../node_modules/@microsoft.azure/autorest.testserver/swagger/head.json
+package-name: @azure/basic-sample
+license-header: MICROSOFT_MIT_NO_VERSION
+package-version: 0.1.0
+```