Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix rendering issue #356

Merged
merged 1 commit into from
Apr 26, 2024
Merged

fix rendering issue #356

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ The degree of coupling between commands relay on SDK can be seen from the follow
![BumpUpNetworkSDK](assets/images/az_cli_bump_up_network_sdk.png)
The SDK packages a batch of APIs, and when one API has new change and is released in a new SDK version,
we have to test and update the commands that use the whole batch of APIs in SDK instead of the one API we care about.
Each time we bump up a SDK, hundreds of tests need to rerun in live and their recording files need to be updated, we also need to fix other commands that are broken by new SDK.
Each time we bump up an SDK, hundreds of tests need to rerun in live and their recording files need to be updated, we also need to fix other commands that are broken by new SDK.
It wasted a lot of time and created a lot of hidden problems. By applying Atomic CLI commands, we can avoid them.

## Overview
Expand All @@ -73,7 +73,7 @@ AAZDev Tool consists of 4 parts:
- API Translators:
They are responsible for translating the API specification into a command model. We've implemented the swagger 2.0 translator which can support to translate the API specs in [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo and [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr) repo.
- Model Editors:
They are used to edit command models. Currently _Workspace Editor_ is implemented. More details are introduced in _Workspace_ paragraph.
They are used to edit command models. Currently, _Workspace Editor_ is implemented. More details are introduced in _Workspace_ paragraph.
- Command Models:
The command models generated from translators and modified in editors will be persisted in a repo called AAZ. The persistence of models can be useful in many ways. More details are introduced in _AAZ Repo_ paragraph.
- Code Generators:
Expand All @@ -89,9 +89,10 @@ A Resource can be translated into a single command or multiple commands under a

Swagger V2 translator uses the `valid part` of url to generate the group part of a command.

The `valid part` of url is the url suffix starts by it's Resource Provider with parameter placeholders replaced by `{}` and locations segment removed.
The `valid part` of url is the url suffix starts by its Resource Provider with parameter placeholders replaced by `{}` and locations segment removed.

The table below show some examples with valid part highlighted.

| Resource Provider | Resource Url | valid part of url |
| ---- | ---- | ---- |
| Microsoft.EdgeOrder | /subscriptions/{subscriptionId}/providers/**Microsoft.EdgeOrder/addresses** | Microsoft.EdgeOrder/addresses |
Expand All @@ -108,7 +109,7 @@ Each segments of valid part corresponds to a group name. The parameter segments

Swagger V2 translator use the HTTP methods to generate the operation part of a command.

The table below show the mapping relation ship between the common command operation name and the resource HTTP methods.
The table below show the mapping relationship between the common command operation name and the resource HTTP methods.

| Common Command Operation Name | Resource HTTP Method |
| ---- | ---- |
Expand All @@ -119,7 +120,7 @@ The table below show the mapping relation ship between the common command operat
| update (by generic) | GET + PUT |
| update (by patch) | PATCH |

For example if a resource has following properties:
For example if a resource has the following properties:

```yaml
resource_id: '/subscriptions/{}/resourcegroups/{}/providers/microsoft.edgeorder/addresses/{}'
Expand Down Expand Up @@ -160,7 +161,7 @@ methods:
- GET
```

Translators will automatic merge them into one `list` commands if their response schemas are the same. If their response schemas are different, a special suffix will be added after `list` operation name to distinguish two commands. And the name can be renamed in editor.
Translators will automatically merge them into one `list` commands if their response schemas are the same. If their response schemas are different, a special suffix will be added after `list` operation name to distinguish two commands. And the name can be renamed in editor.

The `POST` method is special. If a resource has `POST` method only and the last segment of valid part is not a parameter segment, that segment will be used as operation name, else a temporary name will be generated, which can be renamed in editor later.

Expand All @@ -169,7 +170,7 @@ The `POST` method is special. If a resource has `POST` method only and the last
Before developers finish customizing the command models and export them in AAZ repo for persistence, the draft is saved in a workspace.
Workspaces are like containers, they are isolated so that changes in one do not affect the others. Therefore, developers can create as many workspaces as needed for different purposes.

It's possible to add resources from different resource providers, but they should be in the same plane. Currently we only support Management plane.
It's possible to add resources from different resource providers, but they should be in the same plane. Currently, we only support Management plane.
Another note is that a workspace don't allow to add a resource multiple times in different versions. For example, if virtual network resource('/subscriptions/{}/resourcegroups/{}/providers/microsoft.network/virtualnetworks/{}') of version 2021-05-01 is added in a workspace, it's not allowed to add other versions of this resource in this workspace.

Please jump to [Workspace Editor](pages/usage/workspace_editor_usage.md) for more details.
Expand All @@ -178,7 +179,7 @@ Please jump to [Workspace Editor](pages/usage/workspace_editor_usage.md) for mor

The name __AAZ__ comes from the abbreviation of Atomic Azure. This repo is to maintain Atomic Azure Cli command models. You can access this repo by [link](https://github.com/Azure/aaz/tree/main).

There a two folders in the root of AAZ:
There are two folders in the root of AAZ:

- Commands:
This folder provides an index of command models available in AAZ. They are organized in a command tree.
Expand Down Expand Up @@ -214,7 +215,7 @@ The diagram below show the structure of command configuration file.

The commands in a configuration file organized in hierarchy.

There are three sections in every commands:
There are three sections in every command:

- Argument Section:
The arguments defined in argument section and grouped by Argument Group.
Expand Down
Loading