search

Azure / azure-sdk-tools

Tools repository leveraged by the Azure SDK team.
MIT License
114 stars 180 forks source link

Samples documentation management plane SDK #6533

Closed maririos closed 1 year ago

maririos commented 1 year ago

Is there any documentation for generating samples? or guidance per language on how to write their samples? Are there any requirements on the number of samples? is it different for .NET?

We will like to use this information in the new Eng Hub documentation site for our service partners Section: https://eng.ms/docs/products/azure-developer-experience/develop/sdk-samples?tabs=management

weidongxu-microsoft commented 1 year ago

Java, by default enabled, as long as spec has example JSONs (these are required by spec).

dev can turn off via generate-samples=false in autorest option.

Handwritten samples can be added to src/samples/java/<namespace> folder.

msyyc commented 1 year ago

For python, there are "generated_samples" (like here) which is generated by tool with swagger examples. And service can write samples by themselves with https://github.com/Azure/azure-sdk-for-python/wiki/What-to-do-after-generating-the-SDK-code-with-codegen#how-to-write-sample for better usage experience.

tadelesh commented 1 year ago

For Go, samples (examples in Go) are generated by tool automatically in release time. Tool usage could refer this: https://github.com/Azure/autorest.go/blob/main/packages/autorest.gotest/doc/gotest_howto.md#generate-examples

maririos commented 1 year ago

thank you all. Will the autogenerated samples work if the REST API spec is written in TypeSpec?

weidongxu-microsoft commented 1 year ago

@maririos

Currently there is no direct codegen from TypeSpec to SDK (mgmt-plane). It is via TypeSpec to Swagger, then Swagger to SDK.

I think typical TypeSpec to Swagger flow is that examples in TypeSpec folder will be transferred to Swagger folder via typespec-autorest (option examples-directory).

e.g. https://github.com/Azure/azure-rest-api-specs/blob/main/specification/containerservice/Fleet.Management/tspconfig.yaml#L7 to https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/preview/2023-03-15-preview

The result would be a Swagger directory same as usual (with examples). PS: CI will fail if there is no example in Swagger. This would be the automated verification to ensure Swagger contains examples.

The rest would be same OpenAPI to SDK via autorest.

live1206 commented 1 year ago

For dotnet, sample generation is via below command and located in sample folder

dotnet build /t:GenerateTests

Normally, there is no hand-written samples for dotnet. But hand-written scenario tests are located in tests folder.

Detailed documentation of dotnet generation is here

qiaozha commented 1 year ago

For typescript mgmt plane, we have an autorest option --generate-sample=true which is enabled when we release the mgmt plane library. We currently don't have the manual written samples for mgmt plane.

maririos commented 1 year ago

Thank you all. I have added all the information in my draft PR here: https://dev.azure.com/azure-sdk/internal/_git/azure-sdk-docs-eng.ms/pullrequest/783?_a=files&path=/docs/develop/sdk-samples.md

Please take a look to make sure I aggregated the information correctly

maririos commented 1 year ago

Merged and deployed: https://eng.ms/docs/products/azure-developer-experience/develop/sdk-samples

weidongxu-microsoft commented 1 year ago

Java, by default enabled, as long as spec has example JSONs (these are required by spec).

dev can turn off via generate-samples=false in autorest option.

Handwritten samples can be added to src/samples/java/<namespace> folder.

The link of Java is wrong. It points to guide on sample for DPG.

As above, just say "dev can turn off via generate-samples=false in autorest option" would be fine.

maririos commented 1 year ago

Java, by default enabled, as long as spec has example JSONs (these are required by spec). dev can turn off via generate-samples=false in autorest option. Handwritten samples can be added to src/samples/java/<namespace> folder.

The link of Java is wrong. It points to guide on sample for DPG.

As above, just say "dev can turn off via generate-samples=false in autorest option" would be fine.

@weidongxu-microsoft In which cases will the dev want to turn off the samples generation if they are required in order to release?

weidongxu-microsoft commented 1 year ago

@weidongxu-microsoft In which cases will the dev want to turn off the samples generation if they are required in order to release?

I haven't see any service wanted to disable it (theoretically they can disable it and handwrite the samples, but none did that). So I assume we can just omit the line. Maybe you can say in mgmt-plane, generate samples is enabled automatically.

Just don't link to https://github.com/Azure/azure-sdk-for-java/wiki/TypeSpec-Java-Quickstart#examples, it is for data-plane.

maririos commented 1 year ago

@weidongxu-microsoft PR => https://dev.azure.com/azure-sdk/internal/_git/azure-sdk-docs-eng.ms/pullrequest/789