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
* update readme
* add override docs
* add help info
* update examples
* use contoso project in example
* rewording
* add example
---------
Co-authored-by: catalinaperalta <[email protected]>
Use one of the supported commands to get started generating clients from a TypeSpec project.
27
+
27
28
This tool will default to using your current working directory to generate clients in and will
28
29
use it to look for relevant configuration files. To specify a different output directory, use
29
30
the `-o` or `--output-dir` option.
30
31
32
+
To see supported commands, run:
33
+
34
+
```
35
+
tsp-client --help
36
+
```
37
+
38
+
To see supported parameters and options for a specific command, run:
39
+
40
+
```
41
+
tsp-client <command> --help
42
+
```
43
+
44
+
Example using the `init` command:
45
+
46
+
```
47
+
tsp-client init --help
48
+
```
49
+
31
50
### init
32
51
33
52
Initialize the client library directory using a tspconfig.yaml. When running this command pass in a path to a local or remote tspconfig.yaml with the `-c` or `--tsp-config` flag.
@@ -36,24 +55,54 @@ The `init` command generates a directory structure following the standard patter
36
55
37
56
> IMPORTANT: This command should be run from the root of the repository.
Sync and generate client libraries from a TypeSpec project. The `update` command will look for a [tsp-location.yaml](#tsp-locationyaml) file in your current directory to sync a TypeSpec project and generate a client library.
42
67
68
+
Example:
69
+
70
+
```
71
+
tsp-client update
72
+
```
73
+
43
74
### sync
44
75
45
76
Sync a TypeSpec project with the parameters specified in tsp-location.yaml.
46
77
47
78
By default the `sync` command will look for a tsp-location.yaml to get the project details and sync them to a temporary directory called `TempTypeSpecFiles`. Alternately, you can pass in the `--local-spec-repo` flag with the path to your local TypeSpec project to pull those files into your temporary directory.
48
79
80
+
Example:
81
+
82
+
```
83
+
tsp-client sync
84
+
```
85
+
49
86
### generate
50
87
51
88
Generate a client library from a TypeSpec project. The `generate` command should be run after the `sync` command. `generate` relies on the existence of the `TempTypeSpecFiles` directory created by the `sync` command and on an `emitter-package.json` file checked into your repository at the following path: `<repo root>/eng/emitter-package.json`. The `emitter-package.json` file is used to install project dependencies and get the appropriate emitter package.
52
89
90
+
Example:
91
+
92
+
```
93
+
tsp-client generate
94
+
```
95
+
53
96
### convert
54
97
55
98
Convert an existing swagger specification to a TypeSpec project. This command should only be run once to get started working on a TypeSpec project. TypeSpec projects will need to be optimized manually and fully reviewed after conversion. When using this command a path or url to a swagger README file is required through the `--swagger-readme` flag. By default, the converted TypeSpec project will leverage TypeSpec built-in libraries with standard patterns and templates (highly recommended), which will cause discrepancies between the generated TypeSpec and original swagger. If you really don't want this intended discrepancy, add `--fully-compatible` flag to generate a TypeSpec project that is fully compatible with the swagger.
56
99
100
+
Example:
101
+
102
+
```
103
+
tsp-client convert --swagger-readme <path to swagger README file>/readme.md
104
+
```
105
+
57
106
### compare
58
107
59
108
Compares two Swagger definitions to identify the relevant differences between them. This command is useful when comparing an existing Swagger definition with a TypeSpec generated one. The `compare` command requires two parameters: `--lhs` which will typically be the original hand-authored Swagger and `--rhs` which will usually be the folder containing your TypeSpec. The command will generate the Swagger and compare the two definitions. The command will ignore differences in the Swagger that don't
@@ -72,48 +121,40 @@ This command generates the default configuration files used by tsp-client. Run t
72
121
Example:
73
122
74
123
```
75
-
azure-sdk-for-python> tsp-client generate-config-files --package-json <path to @azure-tools/typespec-python emitter clone>\package.json
124
+
tsp-client generate-config-files --package-json <path to emitter repo clone>/package.json
76
125
```
77
126
78
-
### generate-lock-file
79
-
80
-
Generate an emitter-package-lock.json under the eng/ directory based on existing `<repo-root>/eng/emitter-package.json`.
81
-
82
-
## Options
127
+
Example using the `azure-sdk-for-js` and the `@azure-tools/typespec-ts` emitter:
83
128
84
129
```
85
-
--arm Convert ARM swagger specification to TypeSpec [boolean]
86
-
-c, --tsp-config The tspconfig.yaml file to use [string]
87
-
--commit Commit to be used for project init or update [string]
88
-
-d, --debug Enable debug logging [boolean]
89
-
--emitter-options The options to pass to the emitter [string]
90
-
-h, --help Show help [boolean]
91
-
--local-spec-repo Path to local repository with the TypeSpec project [string]
92
-
--no-prompt Skip prompting for output directory confirmation [boolean]
93
-
--save-inputs Don't clean up the temp directory after generation [boolean]
94
-
--skip-sync-and-generate Skip sync and generate during project init [boolean]
95
-
--swagger-readme Path or url to swagger readme file [string]
96
-
-o, --output-dir Specify an alternate output directory for the
97
-
generated files. Default is your current directory [string]
98
-
--repo Repository where the project is defined for init
99
-
or update [string]
100
-
-v, --version Show version number [boolean]
130
+
azure-sdk-for-js> tsp-client generate-config-files --package-json <relative or absolute path to repo clone of @azure-tools/typespec-ts package>/package.json
101
131
```
102
132
103
-
## Examples
133
+
If you need to override dependencies for your emitter-package.json you can create a json file to explicitly list the package and corresponding version you want to override. This will add an `overrides` section in your emitter-package.json that will be used during `npm install` or `npm ci`. [See npm overrides doc.](https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#overrides)
104
134
105
-
Initializing and generating a new client from a `tspconfig.yaml`:
135
+
Example json file with package overrides:
136
+
137
+
```
138
+
{
139
+
"@azure-tools/typespec-python": "0.36.0",
140
+
"@typespec/compiler": "0.61.0"
141
+
}
142
+
```
106
143
107
-
> NOTE: The `init`command must be run from the root of the repository.
0 commit comments