You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ External Contributors can read [Getting Started with OpenAPI Specifications](htt
17
17
18
18
-**Offerings**, **Skus**, and **Features** - These are distinct entities represented in Eco Manager and Service Tree. While the Offering/Sku/Feature entities and hierarchy represent the externally marketed product, **service/components** entities in service tree represent corresponding engineering entities that together power these external products. Refer to [Product Taxonomy](https://dev.azure.com/msazure/AzureWiki/_wiki/wikis/AzureWiki.wiki/40783/Service-Tree-Product-Taxonomy) for details.
19
19
20
-
-**Resource Provider** - When a service onboard new functionality onto ARM, it is required to complete [Resource Provider Registration](https://armwiki.azurewebsites.net/rp_onboarding/ResourceProviderRegistration.html). For existing **Resource Provider to Service Mapping**, refer to [Match resource provider to service](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service)*
20
+
-**Resource Provider** - When a service onboards new functionality onto ARM, it is required to complete [Resource Provider Registration](https://armwiki.azurewebsites.net/rp_onboarding/ResourceProviderRegistration.html). For existing **Resource Provider to Service Mapping**, refer to [Match resource provider to service](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service)*
21
21
22
22
23
23
## Directory Structure
@@ -34,13 +34,13 @@ The structure of the directory should strictly follow these rules:
34
34
>
35
35
> - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities?
36
36
> - Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future?
37
-
> - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that need to be referred cross RP folders should to be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types).
37
+
> - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types).
38
38
> - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex).
39
39
40
-
4.**'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present.
40
+
4.**'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present.
41
41
42
42
43
-
5.**'cadl' Folders**: this folder holds CADL specs of either `resource-manager` or `data-plane`. CADL is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the CADL repo: [CADL tutorial](http://aka.ms/cadlTutorial). You can also ask questions for provide feedback in the teams channel [CADL Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47).
43
+
5.**'cadl' Folders**: this folder holds CADL specs of either `resource-manager` or `data-plane`. CADL is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the CADL repo: [CADL tutorial](http://aka.ms/cadlTutorial). You can also ask questions for providing feedback in the teams channel [CADL Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47).
44
44
45
45
46
46
6.**'Microsoft.{ARMNamespace}' Folders**: the folders are only required under the 'resource-manager' folder, which means only management-plane API specs require to have ARM Namespace in the file path. For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding](https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting).
@@ -56,7 +56,7 @@ The structure of the directory should strictly follow these rules:
56
56
57
57
9.**'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples.
58
58
59
-
> Note: some general guidance for folder names, file names under `specification`:
59
+
> Note: some general guidance for folder names, and file names under `specification`:
60
60
>
61
61
> - Folder names should be singular (ie, 'profile' not 'profiles' ) -- this removes ambiguity for some non-english speakers.
62
62
> - Generic folder names should be lower-case
@@ -110,7 +110,7 @@ The structure should appear like so:
110
110
|\---readme.md
111
111
```
112
112
### Folder Structure for Service Group
113
-
If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboaration, especially supporting:
113
+
If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboration, especially supporting:
114
114
115
115
- To collect API definition of multiple components/services with different versioning cycle in one rp folder
116
116
- To share some common entity types among services or components under the same rp folder.
@@ -174,7 +174,7 @@ Specification files and AutoRest configuration files in one RP folder are better
174
174
175
175
176
176
## Next steps
177
-
The next step in the process after a spec is completed is to generate SDKs and API reference documentation. If you're Microsoft employee, go to the [Azure SDK - Internal Wiki](https://aka.ms/jointhesdk) for more information.
177
+
The next step in the proces://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the entity type sharing cross components or services after a spec is completed is to generate SDKs and API reference documentation. If you're a Microsoft employee, go to the [Azure SDK - Internal Wiki](https://aka.ms/jointhesdk) for more information.
178
178
179
179
External Contributors can read [Getting Started with OpenAPI Specifications](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/Getting%20started%20with%20OpenAPI%20specifications.md).
0 commit comments