Skip to content

Commit 8bea084

Browse files
davidkallesendavidkallesen
committed
docs: update readme
1 parent f3cf7f0 commit 8bea084

File tree

1 file changed

+142
-7
lines changed

1 file changed

+142
-7
lines changed

‎README.md

Lines changed: 142 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@
1818
- [Option **generate server all -h**](#option-generate-server-all--h)
1919
- [Command **options-file**](#command-options-file)
2020
- [Default options-file - ApiGeneratorOptions.json](#default-options-file---apigeneratoroptionsjson)
21+
- [Custom options-file - ApiGeneratorOptions.json](#custom-options-file---apigeneratoroptionsjson)
22+
- [Options for locations explained](#options-for-locations-explained)
23+
- [Syntax](#syntax)
24+
- [Examples](#examples)
25+
- [Other options explained](#other-options-explained)
2126
- [PetStore Example](#petstore-example)
2227
- [Security - supporting role-based security and custom authentication-schemes](#security---supporting-role-based-security-and-custom-authentication-schemes)
2328
- [Roles and authentication-scheme validation](#roles-and-authentication-scheme-validation)
@@ -79,12 +84,12 @@ flowchart TB;
7984
8085
CLI --> ApiGenerator;
8186
CLI --> CodingRules;
82-
87+
8388
ApiGenerator --> ClientCSharp;
8489
ApiGenerator --> ServerMvc;
8590
ApiGenerator --> ServerMinimal;
8691
ApiGenerator .-> Contracts;
87-
92+
8893
ClientCSharp --> Framework;
8994
ClientCSharp .-> Contracts;
9095
ClientCSharp .-> CSharpGenerator;
@@ -181,6 +186,9 @@ COMMANDS:
181186
```powershell
182187
atc-rest-api-generator generate server all -h
183188
189+
DESCRIPTION:
190+
Creates API, domain and host projects.
191+
184192
USAGE:
185193
atc-rest-api-generator.exe generate server all [OPTIONS]
186194
@@ -195,16 +203,24 @@ OPTIONS:
195203
-s, --specificationPath <SPECIFICATIONPATH> Path to Open API specification (directory, file or url)
196204
--optionsPath [OPTIONSPATH] Path to options json-file
197205
--validate-strictMode Use strictmode
206+
--validate-operationIdValidation Use operationId validation
198207
--validate-operationIdCasingStyle [OPERATIONIDCASINGSTYLE] Set casingStyle for operationId. Valid values are: CamelCase (default), KebabCase, PascalCase, SnakeCase
199208
--validate-modelNameCasingStyle [MODELNAMECASINGSTYLE] Set casingStyle for model name. Valid values are: CamelCase, KebabCase, PascalCase (default), SnakeCase
200209
--validate-modelPropertyNameCasingStyle [MODELPROPERTYNAMECASINGSTYLE] Set casingStyle for model property name. Valid values are: CamelCase (default), KebabCase, PascalCase, SnakeCase
201-
--useAuthorization Use authorization
202210
-p, --projectPrefixName <PROJECTPREFIXNAME> Project prefix name (e.g. 'PetStore' becomes 'PetStore.Api.Generated')
211+
--disableCodingRules Disable ATC-Coding-Rules
212+
--useProblemDetailsAsDefaultResponseBody Use ProblemDetails as default responsen body
213+
--endpointsLocation [ENDPOINTSLOCATION] If endpoints-localtion is provided, generated files will be placed here instead of the Endpoints folder
214+
--contractsLocation [CONTRACTSLOCATION] If contracts-localtion is provided, generated files will be placed here instead of the Contracts folder
215+
--handlersLocation [HANDLERSLOCATION] If handlers-localtion is provided, generated files will be placed here instead of the Handlers folder
216+
--usePartialClassForContracts Use Partial-Class for contracts
217+
--usePartialClassForEndpoints Use Partial-Class for endpoints
218+
--removeNamespaceGroupSeparatorInGlobalUsings Remove space between namespace groups in GlobalUsing.cs
219+
--aspnet-output-type [ASPNETOUTPUTTYPE] Set AspNet output type for the generated api. Valid values are: Mvc (default), MinimalApi
220+
--swagger-theme [SWAGGERTHEME] Set Swagger theme for the hosting api. Valid values are: None, Default (default), Light, Dark
203221
--outputSlnPath <OUTPUTSLNPATH> Path to solution file (directory or file)
204222
--outputSrcPath <OUTPUTSRCPATH> Path to generated src projects (directory)
205223
--outputTestPath [OUTPUTTESTPATH] Path to generated test projects (directory)
206-
--disableCodingRules Disable ATC-Coding-Rules
207-
--removeNamespaceGroupSeparatorInGlobalUsings Remove space between namespace groups in GlobalUsing.cs
208224
```
209225

210226
#### Command **options-file**
@@ -225,27 +241,146 @@ COMMANDS:
225241
validate Validate the options file 'ApiGeneratorOptions.json'
226242
```
227243

244+
> **Note:** All values from the options-file will be overriden if pressent from the CLI options.
245+
>
246+
> **Example:** If the usePartialClassForContracts=false in the options-file and the CLI `--usePartialClassForContracts` options set, then the usePartialClassForContracts is true.
247+
228248
#### Default options-file - ApiGeneratorOptions.json
229249

230250
```json
231251
{
232252
"generator": {
233-
"useAuthorization": false,
253+
"aspNetOutputType": "Mvc",
254+
"swaggerThemeMode": "None",
234255
"useRestExtended": true,
256+
"projectName": "",
257+
"projectSuffixName": "",
258+
"contractsLocation": "Contracts.[[apiGroupName]]",
259+
"endpointsLocation": "Endpoints.[[apiGroupName]]",
260+
"handlersLocation": "Handlers.[[apiGroupName]]",
261+
"usePartialClassForContracts": false,
262+
"usePartialClassForEndpoints": false,
263+
"removeNamespaceGroupSeparatorInGlobalUsings": false,
235264
"request": {},
236265
"response": {
237266
"useProblemDetailsAsDefaultBody": false
238267
}
239268
},
240269
"validation": {
241270
"strictMode": false,
271+
"operationIdValidation": false,
242272
"operationIdCasingStyle": "CamelCase",
243273
"modelNameCasingStyle": "PascalCase",
244274
"modelPropertyNameCasingStyle": "CamelCase"
245-
}
275+
},
276+
"includeDeprecatedOperations": false
246277
}
247278
```
248279

280+
#### Custom options-file - ApiGeneratorOptions.json
281+
282+
```json
283+
{
284+
"generator": {
285+
"aspNetOutputType": "MinimalApi",
286+
"swaggerThemeMode": "Dark",
287+
"useRestExtended": true,
288+
"projectName": "",
289+
"projectSuffixName": "",
290+
"contractsLocation": "Contracts.[[apiGroupName]]",
291+
"endpointsLocation": "Endpoints.[[apiGroupName]]",
292+
"handlersLocation": "Handlers.[[apiGroupName]]",
293+
"usePartialClassForContracts": false,
294+
"usePartialClassForEndpoints": false,
295+
"removeNamespaceGroupSeparatorInGlobalUsings": false,
296+
"request": {},
297+
"response": {
298+
"useProblemDetailsAsDefaultBody": false,
299+
"customErrorResponseModel": {
300+
"name": "ErrorResponse",
301+
"description": "Represents an error response.",
302+
"schema": {
303+
"status": {
304+
"dataType": "string?",
305+
"description": "Gets or sets the status of the error."
306+
},
307+
"message": {
308+
"dataType": "string?",
309+
"description": "Gets or sets the error message."
310+
},
311+
"readableMessage": {
312+
"dataType": "string?",
313+
"description": "Gets or sets the readable message."
314+
},
315+
"errorCode": {
316+
"dataType": "string?",
317+
"description": "Gets or sets the error code."
318+
},
319+
"context": {
320+
"dataType": "object?",
321+
"description": "Gets or sets the context information."
322+
}
323+
}
324+
}
325+
},
326+
"client": {
327+
"excludeEndpointGeneration": false,
328+
"httpClientName": "My-ApiClient"
329+
}
330+
},
331+
"validation": {
332+
"strictMode": false,
333+
"operationIdValidation": false,
334+
"operationIdCasingStyle": "CamelCase",
335+
"modelNameCasingStyle": "PascalCase",
336+
"modelPropertyNameCasingStyle": "CamelCase"
337+
},
338+
"includeDeprecatedOperations": false
339+
}
340+
```
341+
342+
#### Options for locations explained
343+
344+
The following options control the file locations for generated files such as contracts, endpoints, and handlers.
345+
You can use specific syntax to define and customize the output file structure.
346+
347+
##### Syntax
348+
349+
For options like `contractsLocation`, `endpointsLocation`, and `handlersLocation`,
350+
you can define paths using placeholders and custom directory names.
351+
352+
The syntax is flexible and allows you to organize files based on grouping or specific requirements.
353+
354+
##### Examples
355+
356+
| Option-Name | Option-Value | Example-file | Generated-output |
357+
|-------------|--------------|--------------|------------------|
358+
| contractsLocation | Contracts | Account.cs | [Project-root]\Contracts\Accounts\Account.cs |
359+
| contractsLocation | Contracts.[[apiGroupName]] | Account.cs | [Project-root]\Contracts\Accounts\Account.cs |
360+
| contractsLocation | Contracts-[[apiGroupName]] | Account.cs | [Project-root]\Contracts\Accounts\Account.cs |
361+
| contractsLocation | [[apiGroupName]].MyContracts | Account.cs | [Project-root]\Accounts\MyContracts\Account.cs |
362+
| contractsLocation | [[apiGroupName]]-MyContracts | Account.cs | [Project-root]\Accounts\MyContracts\Account.cs |
363+
| contractsLocation | [[apiGroupName]] | Account.cs | [Project-root]\Accounts\Account.cs |
364+
| contractsLocation | . | Account.cs | [Project-root]\Account.cs |
365+
366+
> Placeholder Explanation:
367+
>
368+
> - [[apiGroupName]]: A placeholder replaced by the API group name during code generation. This allows grouping files dynamically based on your API structure.
369+
> - [Project-root]: The root directory of your project where the generated files will be placed.
370+
371+
By using these options, you can effectively organize generated files into meaningful folder structures, ensuring clarity and scalability in your project layout.
372+
373+
#### Other options explained
374+
375+
The `projectSuffixName` extend `projectName` like the example:
376+
377+
| projectName | projectSuffixName | Generated project name | Reson |
378+
|-------------|-------------------|------------------------|-------|
379+
| PetStore | | PetStore.Api.Generated | default is `Api.Generated` |
380+
| PetStore | MyApi | PetStore.MyApi | |
381+
| PetStore | Foo.Api | PetStore.Foo.Api | |
382+
| PetStore | Bar-Api | PetStore.Bar.Api | |
383+
249384
## PetStore Example
250385

251386
The following command will generate an API that implements the offcial Pet Store example from Swagger.

0 commit comments

Comments
 (0)