Improve Radius.Core resource type documentation, property descriptions, and default values

[zachcasper]

Summary

This pull request improves the documentation for the Radius.Core resource types (applications, environments, recipePacks, bicepSettings, and terraformSettings) so that platform engineers and developers can understand and use them from the resource type definition alone. It combines two related efforts: expanded, example-driven type-level documentation and a full pass over every schema property description. The changes are authored in TypeSpec and reflected in the generated Go models and the OpenAPI specification, and are verified by the unit tests.

The most important changes are:

Resource Type Documentation Improvements:

• Expanded the type-level descriptions for ApplicationResource, BicepSettingsResource, EnvironmentResource, RecipePackResource, and TerraformSettingsResource to include detailed explanations, Bicep and CLI examples, and deployment instructions.

Property Description Improvements:

• Added (Required), (Optional), and (Read Only) prefixes to every schema property across the five resource types, matching each property's schema optionality.
• Rewrote the property descriptions to be accurate, precise, and helpful for platform engineers, conforming to the resource-types-contrib documentation standards.
• Documented default values on optional properties. For example, environments.providers now notes it defaults to Kubernetes in the default namespace, and environments.recipePacks notes it defaults to the default Recipe Pack in the default resource group.
• Standardized on "Bicep settings" and "Terraform settings" naming throughout.

Testing and Validation:

• Updated the unit test in pkg/ucp/initializer/service_test.go to check that the resource type descriptions contain the expected prefixes, ensuring the documentation is present and correct in the API summary.

Reason for change

These changes significantly improve the developer and platform engineer experience by making the API documentation more comprehensive and actionable, and by surfacing default values that were previously undocumented.

Fixes #12429
Fixes #12430
Fixes #12431

How to test

rad resource-type show Radius.Core/applications
rad resource-type show Radius.Core/environments
rad resource-type show Radius.Core/recipePacks
rad resource-type show Radius.Core/terraformSettings
rad resource-type show Radius.Core/bicepSettings

Also view in the dashboard. Screenshots below:

Radius.Core/applications before:

Radius.Core/applications after:

Radius.Core/environments before:

Radius.Core/environments after:

Radius.Core/recipePacks before:

Radius.Core/recipePacks after:

Radius.Core/terraformSettings before:

Radius.Core/terraformSettings after:

Radius.Core/bicepSettings before:

Radius.Core/bicepSettings after:

[Copilot]

Pull request overview

This PR improves developer/platform-engineer documentation for key Radius.Core resource types by expanding their description text (TypeSpec → generated Go models/responses → OpenAPI), and updates a unit test to validate that the richer descriptions are present in the registered resource type summaries.

Changes:

• Expanded @doc(...) descriptions for applications, environments, recipePacks, bicepSettings, and terraformSettings in TypeSpec with usage guidance and examples.
• Regenerated/updated corresponding OpenAPI and Go generated artifacts so the richer documentation flows through the API surface.
• Updated pkg/ucp/initializer/service_test.go to validate the new description content is present.

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
typespec/Radius.Core/applications.tsp	Adds expanded developer documentation for Radius.Core/applications, including Bicep/CLI examples.
typespec/Radius.Core/bicepSettings.tsp	Adds expanded documentation for Radius.Core/bicepSettings including registry auth examples.
typespec/Radius.Core/environments.tsp	Adds expanded documentation for Radius.Core/environments including CLI and Bicep examples and defaults.
typespec/Radius.Core/recipePacks.tsp	Adds expanded documentation for Radius.Core/recipePacks including authoring and referencing examples.
typespec/Radius.Core/terraformSettings.tsp	Adds expanded documentation for Radius.Core/terraformSettings including private registry + provider mirror examples.
swagger/specification/radius/resource-manager/Radius.Core/preview/2025-08-01-preview/openapi.json	Updates OpenAPI descriptions to match the new expanded TypeSpec docs.
pkg/corerp/api/v20250801preview/zz_generated_models.go	Updates generated Go model comments to carry the new resource type documentation.
pkg/corerp/api/v20250801preview/zz_generated_responses.go	Updates generated Go response comments to carry the new resource type documentation.
pkg/ucp/initializer/service_test.go	Adjusts the test to validate the updated description content is present for registered types.

Files not reviewed (2)

• pkg/corerp/api/v20250801preview/zz_generated_models.go: Generated file
• pkg/corerp/api/v20250801preview/zz_generated_responses.go: Generated file

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.51%. Comparing base (375f076) to head (d027ff6).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #12439      +/-   ##
==========================================
+ Coverage   53.46%   53.51%   +0.04%     
==========================================
  Files         758      758              
  Lines       49254    49326      +72     
==========================================
+ Hits        26333    26396      +63     
- Misses      20475    20482       +7     
- Partials     2446     2448       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Functional Tests - corerp-cloud

30 tests  ±0   27 ✅ ±0   52m 44s ⏱️ + 4m 19s
 2 suites ±0    1 💤 ±0 
 1 files   ±0    2 ❌ ±0 

For more details on these failures, see this check.

Results for commit d027ff6. ± Comparison against base commit 375f076.

[radius-functional-tests]

Radius functional test overview

🔍 Go to test action run

Click here to see the test run details

Name	Value
Repository	zachcasper/radius
Commit ref	bd259a8
Unique ID	func6a1bb56b96
Image tag	pr-func6a1bb56b96

• Dapr: 1.14.4
• Azure KeyVault CSI driver: 1.4.2
• Azure Workload identity webhook: 1.3.0
• Bicep recipe location ghcr.io/radius-project/dev/test/testrecipes/test-bicep-recipes/<name>:pr-func6a1bb56b96
• Terraform recipe location http://tf-module-server.radius-test-tf-module-server.svc.cluster.local/<name>.zip (in cluster)
• applications-rp test image location: ghcr.io/radius-project/dev/applications-rp:pr-func6a1bb56b96
• dynamic-rp test image location: ghcr.io/radius-project/dev/dynamic-rp:pr-func6a1bb56b96
• controller test image location: ghcr.io/radius-project/dev/controller:pr-func6a1bb56b96
• ucp test image location: ghcr.io/radius-project/dev/ucpd:pr-func6a1bb56b96
• deployment-engine test image location: ghcr.io/radius-project/deployment-engine:latest

Test Status

⌛ Building Radius and pushing container images for functional tests...
✅ Container images build succeeded
⌛ Publishing Bicep Recipes for functional tests...
✅ Recipe publishing succeeded
⌛ Starting ucp-cloud functional tests...
⌛ Starting corerp-cloud functional tests...
❌ ucp-cloud functional test failed. Please check the logs for more details
❌ corerp-cloud functional test failed. Please check the logs for more details

[lakshmimsft]

we can delete 'For AWS, set the account ID and region' or include details for all providers