{"id":22070289,"url":"https://github.com/atc-net/atc-rest-api-generator","last_synced_at":"2025-07-24T08:35:51.555Z","repository":{"id":40493517,"uuid":"320370533","full_name":"atc-net/atc-rest-api-generator","owner":"atc-net","description":"A REST API code generator from OpenAPI Specification in YAML or Json file format","archived":false,"fork":false,"pushed_at":"2025-03-03T11:29:38.000Z","size":4531,"stargazers_count":19,"open_issues_count":45,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-23T20:07:55.678Z","etag":null,"topics":["api","code-generator","command-line-tool","openapi","rest","rest-api","swagger"],"latest_commit_sha":null,"homepage":"https://atc-net.github.io/repository/atc-rest-api-generator","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atc-net.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-12-10T19:30:56.000Z","updated_at":"2025-06-25T16:33:49.000Z","dependencies_parsed_at":"2024-05-13T12:33:19.663Z","dependency_job_id":"3110b68d-22ac-4395-92b9-77e9556d8dc8","html_url":"https://github.com/atc-net/atc-rest-api-generator","commit_stats":{"total_commits":732,"total_committers":9,"mean_commits":81.33333333333333,"dds":0.4713114754098361,"last_synced_commit":"a0aa40fb07ded25f5b36b7b68213680359c465c7"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/atc-net/atc-rest-api-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atc-net%2Fatc-rest-api-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atc-net%2Fatc-rest-api-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atc-net%2Fatc-rest-api-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atc-net%2Fatc-rest-api-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atc-net","download_url":"https://codeload.github.com/atc-net/atc-rest-api-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atc-net%2Fatc-rest-api-generator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266815221,"owners_count":23988563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","code-generator","command-line-tool","openapi","rest","rest-api","swagger"],"created_at":"2024-11-30T20:15:51.988Z","updated_at":"2025-07-24T08:35:51.131Z","avatar_url":"https://github.com/atc-net.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ATC-NET REST API Generator\n\n[![NuGet Version](https://img.shields.io/nuget/v/atc-rest-api-generator.svg?logo=nuget\u0026style=for-the-badge)](https://www.nuget.org/packages/atc-rest-api-generator)\n\n## Table of content\n\n- [ATC-NET REST API Generator](#atc-net-rest-api-generator)\n  - [Table of content](#table-of-content)\n  - [Projects in the repository](#projects-in-the-repository)\n  - [Project dependency graph](#project-dependency-graph)\n  - [CLI Tool](#cli-tool)\n  - [Prerequisites](#prerequisites)\n    - [Requirements](#requirements)\n    - [Installation](#installation)\n    - [Update](#update)\n    - [Usage](#usage)\n      - [Option **-h | --help**](#option--h----help)\n      - [Option **generate server all -h**](#option-generate-server-all--h)\n      - [Command **options-file**](#command-options-file)\n      - [Default options-file - ApiGeneratorOptions.json](#default-options-file---apigeneratoroptionsjson)\n      - [Custom options-file - ApiGeneratorOptions.json](#custom-options-file---apigeneratoroptionsjson)\n      - [Options for locations explained](#options-for-locations-explained)\n        - [Syntax](#syntax)\n        - [Examples](#examples)\n      - [Other options explained](#other-options-explained)\n  - [PetStore Example](#petstore-example)\n  - [Security - supporting role-based security and custom authentication-schemes](#security---supporting-role-based-security-and-custom-authentication-schemes)\n    - [Roles and authentication-scheme validation](#roles-and-authentication-scheme-validation)\n    - [Logic for determining `[Authorize]` or `[AllowAnonymous]` attributes](#logic-for-determining-authorize-or-allowanonymous-attributes)\n    - [Example](#example)\n  - [OpenApi Snippets](#openapi-snippets)\n    - [List of items](#list-of-items)\n    - [List of items with a custom PaginationResult](#list-of-items-with-a-custom-paginationresult)\n    - [List of items with a built-in Pagination](#list-of-items-with-a-built-in-pagination)\n    - [AsyncEnumerable of items](#asyncenumerable-of-items)\n    - [AsyncEnumerable of items with a custom PaginationResult](#asyncenumerable-of-items-with-a-custom-paginationresult)\n    - [AsyncEnumerable of items with a built-in Pagination](#asyncenumerable-of-items-with-a-built-in-pagination)\n    - [Custom PaginationResult with query parameters](#custom-paginationresult-with-query-parameters)\n  - [How to contribute](#how-to-contribute)\n\n## Projects in the repository\n\n|Project|Target Framework|Description|Nuget Download Link|\n|---|---|---|---|\n|[Atc.Rest.ApiGenerator](src/Atc.Rest.ApiGenerator) | net9.0 | Atc.Rest.ApiGenerator is a WebApi C# code generator using a OpenApi 3.0.x specification YAML file. | [![Nuget](https://img.shields.io/nuget/dt/Atc.Rest.ApiGenerator?logo=nuget\u0026style=flat-square)](https://www.nuget.org/packages/Atc.Rest.ApiGenerator) |\n|[Atc.Rest.ApiGenerator.CLI](src/Atc.Rest.ApiGenerator.CLI) |net9.0 | A CLI tool that use Atc.Rest.ApiGenerator to create/update a project specified by a OpenApi 3.0.x specification YAML file. | [![Nuget](https://img.shields.io/nuget/dt/atc-rest-api-generator?logo=nuget\u0026style=flat-square)](https://www.nuget.org/packages/atc-rest-api-generator) |\n|[Atc.Rest.ApiGenerator.CodingRules](src/Atc.Rest.ApiGenerator.CodingRules) | net9.0| Create/update atc coding rules for the generated code | |\n|[Atc.Rest.ApiGenerator.Contracts](src/Atc.Rest.ApiGenerator.Contracts) | net9.0| Shared contracts and interfaces for the generated code. | |\n|[Atc.Rest.ApiGenerator.Framework.Mvc](src/Atc.Rest.ApiGenerator.Framework.Mvc) | net9.0| Provides support for generating ASP.NET MVC / Controller based REST API server implementations. | |\n|[Atc.Rest.ApiGenerator.Framework.Minimal](src/Atc.Rest.ApiGenerator.Framework.Minimal) | net9.0| Provides support for generating MinimalAPI based REST server implementations. | |\n|[Atc.Rest.ApiGenerator.Client.CSharp](src/Atc.Rest.ApiGenerator.Client.CSharp) | net9.0| Generates C# client code for interacting with the generated REST APIs. | |\n|[Atc.Rest.ApiGenerator.Framework](src/Atc.Rest.ApiGenerator.Framework) | net9.0| Shared framework components and utilities for the API generator projects. | |\n|[Atc.Rest.ApiGenerator.OpenApi](src/Atc.Rest.ApiGenerator.OpenApi) | net9.0| Handles OpenAPI specification parsing and manipulation for the API generator. | |\n|[Atc.Rest.ApiGenerator.Nuget](src/Atc.Rest.ApiGenerator.Nuget) | net9.0| Manages NuGet packages required by the generated code and frameworks. | |\n|[Atc.CodeGeneration.CSharp](src/Atc.CodeGeneration.CSharp) | net9.0| Provides utilities and functionalities for generating C# code. | |\n\n## Project dependency graph\n\n```mermaid\nflowchart TB;\n    CLI[Atc.Rest.ApiGenerator.CLI]\n    Contracts[Atc.Rest.ApiGenerator.Contracts];\n    ApiGenerator[Atc.Rest.ApiGenerator];\n    CodingRules[Atc.Rest.ApiGenerator.CodingRules]\n    ClientCSharp[Atc.Rest.ApiGenerator.Client.CSharp];\n    ServerMvc[Atc.Rest.ApiGenerator.Framework.Mvc];\n    ServerMinimal[Atc.Rest.ApiGenerator.Framework.Minimal];\n    Framework[Atc.Rest.ApiGenerator.Framework];\n    Nuget[Atc.Rest.ApiGenerator.Nuget];\n    CSharpGenerator[Atc.CodeGeneration.CSharp];\n    OpenApi[Atc.Rest.ApiGenerator.OpenApi];\n\n    style CLI fill:#007FFF;\n    style Contracts fill:#57A64A;\n    style ApiGenerator fill:#;\n    style CodingRules fill:#;\n    style ClientCSharp fill:#B35A2D;\n    style ServerMvc fill:#B35A2D;\n    style ServerMinimal fill:#B35A2D;\n    style Framework fill:#;\n    style Nuget fill:#;\n    style CSharpGenerator fill:#;\n    style OpenApi fill:#;\n\n    CLI --\u003e ApiGenerator;\n    CLI --\u003e CodingRules;\n\n    ApiGenerator --\u003e ClientCSharp;\n    ApiGenerator --\u003e ServerMvc;\n    ApiGenerator --\u003e ServerMinimal;\n    ApiGenerator .-\u003e Contracts;\n\n    ClientCSharp --\u003e Framework;\n    ClientCSharp .-\u003e Contracts;\n    ClientCSharp .-\u003e CSharpGenerator;\n\n    ServerMvc --\u003e Framework;\n    ServerMvc .-\u003e Contracts;\n    ServerMvc .-\u003e CSharpGenerator;\n\n    ServerMinimal --\u003e Framework;\n    ServerMinimal .-\u003e Contracts;\n    ServerMinimal .-\u003e CSharpGenerator;\n\n    Framework --\u003e Nuget;\n    Framework --\u003e OpenApi;\n    Framework .-\u003e Contracts;\n    Framework --\u003e CSharpGenerator;\n\n    OpenApi ..-\u003e Contracts;\n```\n\n## CLI Tool\n\nThe `atc-rest-api-generator` is a cross platform command line application known as CLI tool.\n\nThe main purpose of this application is to create and maintain a REST-API based on an Open-API specification file using a `Design First` approach.\n\nThe `atc-rest-api-generator` can be categorized as a `Rapid Application Development Tool` for REST-API in .NET/C#.\n\n## Prerequisites\n\nTo get the benefit out of this CLI tool, a `Design first` approach of the REST API in a `OpenAPI specification` should be in effect. The CLI tool needs a `OpenAPI specification` in `yaml` or `json` file format provided as the argument value for parameter `--specificationPath` or the short-hand-version `-s`.\n\nRead more about REST API design in [ATC DevOps Playbook](https://atc-net.github.io/manuals/devops-playbook#rest-api-design).\n\nRecommended tools for working with OpenAPI specifications:\n\n- [Stoplight.io](https://stoplight.io/). Read more about it in the [Stoplight Documentation](https://meta.stoplight.io/) and get it from [Stoplight Download](https://stoplight.io/studio)\n- [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) extension for Visual Studio Code\n\n### Requirements\n\n- [.NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)\n\n### Installation\n\nThe tool can be installed as a .NET Core global tool by the following command\n\n```powershell\ndotnet tool install --global atc-rest-api-generator\n```\n\nor by following the instructions [here](https://www.nuget.org/packages/atc-rest-api-generator/) to install a specific version of the tool.\n\nA successful installation will output something like\n\n```powershell\nThe tool can be invoked by the following command: atc-rest-api-generator\nTool 'atc-rest-api-generator' (version '2.0.xxx') was successfully installed.`\n```\n\n### Update\n\nThe tool can be updated by following command\n\n```powershell\ndotnet tool update --global atc-rest-api-generator\n```\n\n### Usage\n\nSince the tool is published as a .NET Tool, it can be launched from anywhere using any shell or command-line interface by calling **atc-rest-api-generator**. The help information is displayed when providing the `--help` argument to **atc-rest-api-generator**\n\n#### Option **-h | --help**\n\n```powershell\natc-rest-api-generator -h\n\nUSAGE:\n    atc-rest-api-generator.exe [OPTIONS]\n\nOPTIONS:\n    -h, --help       Prints help information\n        --verbose    Use verbose for more debug/trace information\n        --version    Display version\n\nCOMMANDS:\n    options-file    Commands for the options file 'ApiGeneratorOptions.json'\n    generate        Operations related to generation of code\n    validate        Operations related to validation of specifications\n```\n\n#### Option **generate server all -h**\n\n```powershell\natc-rest-api-generator generate server all -h\n\nDESCRIPTION:\nCreates API, domain and host projects.\n\nUSAGE:\n    atc-rest-api-generator.exe generate server all [OPTIONS]\n\nEXAMPLES:\n    atc-rest-api-generator.exe generate server -s c:\\temp\\MyProject\\api.yml -p MyApi .\n    atc-rest-api-generator.exe generate server all -s c:\\temp\\MyProject\\api.yml -p MyApi .\n    atc-rest-api-generator.exe generate server all -s c:\\temp\\MyProject\\api.yml -p MyApi --outputSlnPath c:\\temp\\MyProject --outputSrcPath c:\\temp\\MyProject\\src\n\nOPTIONS:\n    -h, --help                                                                    Prints help information\n        --verbose                                                                 Use verbose for more debug/trace information\n    -s, --specificationPath \u003cSPECIFICATIONPATH\u003e                                   Path to Open API specification (directory, file or url)\n        --optionsPath [OPTIONSPATH]                                               Path to options json-file\n        --validate-strictMode                                                     Use strictmode\n        --validate-operationIdValidation                                          Use operationId validation\n        --validate-operationIdCasingStyle [OPERATIONIDCASINGSTYLE]                Set casingStyle for operationId. Valid values are: CamelCase (default), KebabCase, PascalCase, SnakeCase\n        --validate-modelNameCasingStyle [MODELNAMECASINGSTYLE]                    Set casingStyle for model name. Valid values are: CamelCase, KebabCase, PascalCase (default), SnakeCase\n        --validate-modelPropertyNameCasingStyle [MODELPROPERTYNAMECASINGSTYLE]    Set casingStyle for model property name. Valid values are: CamelCase (default), KebabCase, PascalCase, SnakeCase\n    -p, --projectPrefixName \u003cPROJECTPREFIXNAME\u003e                                   Project prefix name (e.g. 'PetStore' becomes 'PetStore.Api.Generated')\n        --disableCodingRules                                                      Disable ATC-Coding-Rules\n        --useProblemDetailsAsDefaultResponseBody                                  Use ProblemDetails as default responsen body\n        --endpointsLocation [ENDPOINTSLOCATION]                                   If endpoints-localtion is provided, generated files will be placed here instead of the Endpoints folder\n        --endpointsNamespace [ENDPOINTSNAMESPACE]                                 If endpoints-namespace is provided, generated files will be placed here instead of the Endpoints namespace\n        --contractsLocation [CONTRACTSLOCATION]                                   If contracts-localtion is provided, generated files will be placed here instead of the Contracts folder\n        --contractsNamespace [CONTRACTSNAMESPACE]                                 If contracts-namespace is provided, generated files will be placed here instead of the Contracts namespace\n        --handlersLocation [HANDLERSLOCATION]                                     If handlers-localtion is provided, generated files will be placed here instead of the Handlers folder\n        --handlersNamespace [HANDLERSNAMESPACE]                                   If handlers-namespace is provided, generated files will be placed here instead of the Handlers namespace\n        --usePartialClassForContracts                                             Use Partial-Class for contracts\n        --usePartialClassForEndpoints                                             Use Partial-Class for endpoints\n        --removeNamespaceGroupSeparatorInGlobalUsings                             Remove space between namespace groups in GlobalUsing.cs\n        --aspnet-output-type [ASPNETOUTPUTTYPE]                                   Set AspNet output type for the generated api. Valid values are: Mvc (default), MinimalApi\n        --swagger-theme [SWAGGERTHEME]                                            Set Swagger theme for the hosting api. Valid values are: None, Default (default), Light, Dark\n        --outputSlnPath \u003cOUTPUTSLNPATH\u003e                                           Path to solution file (directory or file)\n        --outputSrcPath \u003cOUTPUTSRCPATH\u003e                                           Path to generated src projects (directory)\n        --outputTestPath [OUTPUTTESTPATH]                                         Path to generated test projects (directory)\n```\n\n#### Command **options-file**\n\n```powershell\nUSAGE:\n    atc-rest-api-generator.exe options-file [OPTIONS] \u003cCOMMAND\u003e\n\nEXAMPLES:\n    atc-rest-api-generator.exe options-file create\n    atc-rest-api-generator.exe options-file validate\n\nOPTIONS:\n    -h, --help    Prints help information\n\nCOMMANDS:\n    create      Create default options file 'ApiGeneratorOptions.json' if it doesn´t exist\n    validate    Validate the options file 'ApiGeneratorOptions.json'\n```\n\n\u003e **Note:** All values from the options-file will be overriden if pressent from the CLI options.\n\u003e\n\u003e **Example:** If the usePartialClassForContracts=false in the options-file and the CLI `--usePartialClassForContracts` options set, then the usePartialClassForContracts is true.\n\n#### Default options-file - ApiGeneratorOptions.json\n\n```json\n{\n  \"generator\": {\n    \"aspNetOutputType\": \"Mvc\",\n    \"swaggerThemeMode\": \"None\",\n    \"useRestExtended\": true,\n    \"projectName\": \"\",\n    \"projectSuffixName\": \"\",\n    \"contractsLocation\": \"Contracts.[[apiGroupName]]\",\n    \"contractsNamespace\": \"Contracts.[[apiGroupName]]\",\n    \"endpointsLocation\": \"Endpoints.[[apiGroupName]]\",\n    \"endpointsNamespace\": \"Endpoints.[[apiGroupName]]\",\n    \"handlersLocation\": \"Handlers.[[apiGroupName]]\",\n    \"handlersNamespace\": \"Handlers.[[apiGroupName]]\",\n    \"usePartialClassForContracts\": false,\n    \"usePartialClassForEndpoints\": false,\n    \"removeNamespaceGroupSeparatorInGlobalUsings\": false,\n    \"request\": {},\n    \"response\": {\n      \"useProblemDetailsAsDefaultBody\": false\n    }\n  },\n  \"validation\": {\n    \"strictMode\": false,\n    \"operationIdValidation\": false,\n    \"operationIdCasingStyle\": \"CamelCase\",\n    \"modelNameCasingStyle\": \"PascalCase\",\n    \"modelPropertyNameCasingStyle\": \"CamelCase\"\n  },\n  \"includeDeprecatedOperations\": false\n}\n```\n\n#### Custom options-file - ApiGeneratorOptions.json\n\n```json\n{\n    \"generator\": {\n      \"aspNetOutputType\": \"MinimalApi\",\n      \"swaggerThemeMode\": \"Dark\",\n      \"useRestExtended\": true,\n      \"projectName\": \"\",\n      \"projectSuffixName\": \"\",\n      \"contractsLocation\": \"Contracts.[[apiGroupName]]\",\n      \"contractsNamespace\": \"Contracts.[[apiGroupName]]\",\n      \"endpointsLocation\": \"Endpoints.[[apiGroupName]]\",\n      \"endpointsNamespace\": \"Endpoints.[[apiGroupName]]\",\n      \"handlersLocation\": \"Handlers.[[apiGroupName]]\",\n      \"handlersNamespace\": \"Handlers.[[apiGroupName]]\",\n      \"usePartialClassForContracts\": false,\n      \"usePartialClassForEndpoints\": false,\n      \"removeNamespaceGroupSeparatorInGlobalUsings\": false,\n      \"request\": {},\n      \"response\": {\n        \"useProblemDetailsAsDefaultBody\": false,\n        \"customErrorResponseModel\": {\n          \"name\": \"ErrorResponse\",\n          \"description\": \"Represents an error response.\",\n          \"schema\": {\n            \"status\": {\n              \"dataType\": \"string?\",\n              \"description\": \"Gets or sets the status of the error.\"\n            },\n            \"message\": {\n              \"dataType\": \"string?\",\n              \"description\": \"Gets or sets the error message.\"\n            },\n            \"readableMessage\": {\n              \"dataType\": \"string?\",\n              \"description\": \"Gets or sets the readable message.\"\n            },\n            \"errorCode\": {\n              \"dataType\": \"string?\",\n              \"description\": \"Gets or sets the error code.\"\n            },\n            \"context\": {\n              \"dataType\": \"object?\",\n              \"description\": \"Gets or sets the context information.\"\n            }\n          }\n        }\n      },\n      \"client\": {\n        \"excludeEndpointGeneration\": false,\n        \"httpClientName\": \"My-ApiClient\"\n      }\n    },\n    \"validation\": {\n      \"strictMode\": false,\n      \"operationIdValidation\": false,\n      \"operationIdCasingStyle\": \"CamelCase\",\n      \"modelNameCasingStyle\": \"PascalCase\",\n      \"modelPropertyNameCasingStyle\": \"CamelCase\"\n    },\n    \"includeDeprecatedOperations\": false\n}\n```\n\n#### Options for locations explained\n\nThe following options control the file locations for generated files such as contracts, endpoints, and handlers.\nYou can use specific syntax to define and customize the output file structure.\n\n##### Syntax\n\nFor options like `contractsLocation`, `contractsNamespace`, `endpointsLocation`, `endpointsNamespace`, `handlersLocation`, `handlersNamespace`,\nyou can define paths using placeholders and custom directory names.\n\nThe syntax is flexible and allows you to organize files based on grouping or specific requirements.\n\n##### Examples\n\n| Option-Name | Option-Value | Example-file | Generated-output |\n|-------------|--------------|--------------|------------------|\n| contractsLocation  | Contracts                    | Account.cs | [Project-root]\\Contracts\\Accounts\\Account.cs   |\n| contractsLocation  | Contracts.[[apiGroupName]]   | Account.cs | [Project-root]\\Contracts\\Accounts\\Account.cs   |\n| contractsLocation  | Contracts-[[apiGroupName]]   | Account.cs | [Project-root]\\Contracts\\Accounts\\Account.cs   |\n| contractsLocation  | [[apiGroupName]].MyContracts | Account.cs | [Project-root]\\Accounts\\MyContracts\\Account.cs |\n| contractsLocation  | [[apiGroupName]]-MyContracts | Account.cs | [Project-root]\\Accounts\\MyContracts\\Account.cs |\n| contractsLocation  | [[apiGroupName]]             | Account.cs | [Project-root]\\Accounts\\Account.cs             |\n| contractsLocation  | .                            | Account.cs | [Project-root]\\Account.cs                      |\n| contractsNamespace | Contracts                    | Account.cs | [Project-root].Contracts.Accounts.Account.cs   |\n| contractsNamespace | Contracts.[[apiGroupName]]   | Account.cs | [Project-root].Contracts.Accounts.Account.cs   |\n| contractsNamespace | Contracts-[[apiGroupName]]   | Account.cs | [Project-root].Contracts.Accounts.Account.cs   |\n| contractsNamespace | [[apiGroupName]].MyContracts | Account.cs | [Project-root].Accounts.MyContracts.Account.cs |\n| contractsNamespace | [[apiGroupName]]-MyContracts | Account.cs | [Project-root].Accounts.MyContracts.Account.cs |\n| contractsNamespace | [[apiGroupName]]             | Account.cs | [Project-root].Accounts.Account.cs             |\n| contractsNamespace | .                            | Account.cs | [Project-root].Account.cs                      |\n\n\u003e Placeholder Explanation:\n\u003e\n\u003e - [[apiGroupName]]: A placeholder replaced by the API group name during code generation. This allows grouping files dynamically based on your API structure.\n\u003e - [Project-root]: The root directory of your project where the generated files will be placed.\n\nBy using these options, you can effectively organize generated files into meaningful folder structures, ensuring clarity and scalability in your project layout.\n\n#### Other options explained\n\nThe `projectSuffixName` extend `projectName` like the example:\n\n| projectName | projectSuffixName | Generated project name | Reason                     |\n|-------------|-------------------|------------------------|----------------------------|\n| PetStore    |                   | PetStore.Api.Generated | default is `Api.Generated` |\n| PetStore    | MyApi             | PetStore.MyApi         |                            |\n| PetStore    | Foo.Api           | PetStore.Foo.Api       |                            |\n| PetStore    | Bar-Api           | PetStore.Bar.Api       |                            |\n\n## PetStore Example\n\nThe following command will generate an API that implements the offcial Pet Store example from Swagger.\n\n```powershell\natc-rest-api-generator generate server all `\n    --validate-strictMode false `\n    -s https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml `\n    -p PetStore `\n    --outputSlnPath \u003cMY_PROJECT_FOLDER\u003e `\n    --outputSrcPath \u003cMY_PROJECT_FOLDER\u003e\\src `\n    --outputTestPath \u003cMMY_PROJECT_FOLDER\u003e\\test `\n    --disableCodingRules `\n    --verbose\n```\n\nReplace `\u003cMY_PROJECT_FOLDER\u003e` with an absolute path where the projects should be created. For example,\nto put the generated solution in a folder called `C:\\PetStore`, do the following:\n\n```powershell\natc-rest-api-generator generate server all `\n    --validate-strictMode false `\n    -s https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml `\n    -p PetStore `\n    --outputSlnPath C:\\PetStore `\n    --outputSrcPath C:\\PetStore\\src `\n    --outputTestPath C:\\PetStore\\test `\n    --disableCodingRules `\n    --verbose\n```\n\nThe following is generated by running the above command:\n\n```mermaid\nflowchart TB;\n    CMD[command: generate server all] --\u003e HOST[Host project] \u0026 API[API project] \u0026 DOMAIN[Domain project];\n    HOST-.-\u003e API;\n    API-.-\u003e DOMAIN;\n```\n\n- The Host-project is the layer for the `.NET WebApi` application. Project suffix: `.Api`.\n- The API-project is the layer with all the contracts, interfaces, result classes and endpoints. Project suffix: `.Api.Generated`.\n- The Domain-project is the layer where handlers can be implemented with necessary business logic. Project suffix: `.Domain`.\n\nRunning the above command produces the following output:\n\n```powershell\n     _      ____    ___      ____                                        _\n    / \\    |  _ \\  |_ _|    / ___|   ___   _ __     ___   _ __    __ _  | |_    ___    _ __\n   / _ \\   | |_) |  | |    | |  _   / _ \\ | `_ \\   / _ \\ | `__|  / _` | | __|  / _ \\  | `__|\n  / ___ \\  |  __/   | |    | |_| | |  __/ | | | | |  __/ | |    | (_| | | |_  | (_) | | |\n /_/   \\_\\ |_|     |___|    \\____|  \\___| |_| |_|  \\___| |_|     \\__,_|  \\__|  \\___/  |_|\n\n🔽 Fetching api specification\n     Download from: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml\n     Download time: 390.229 ms\n🔍 Working on validation\n     CR0103: Schema - Missing title on object type '#/components/schemas/Pet'.\n     CR0101: Schema - Missing title on array type '#/components/schemas/Pets'.\n     CR0103: Schema - Missing title on object type '#/components/schemas/Error'.\n     CR0203: Operation - OperationId should start with the prefix 'Get' or 'List' for operation 'showPetById'.\n     CR0214: Operation - Missing NotFound response type for operation 'ShowPetById', required by url parameter.\n🔷 Working on server api generation (PetStore.Api.Generated)\n     CR0801 - Old project does not exist\n🟢   src:  PetStore.Api.Generated.csproj created\n🟢   src:  ApiRegistration.cs created\n🟢   src:  Contracts\\Pets\\Models\\Error.cs created\n🟢   src:  Contracts\\Pets\\Models\\Pet.cs created\n🟢   src:  Contracts\\Pets\\Models\\Pets.cs created\n🟢   src:  Contracts\\Pets\\Parameters\\ListPetsParameters.cs created\n🟢   src:  Contracts\\Pets\\Parameters\\ShowPetByIdParameters.cs created\n🟢   src:  Contracts\\Pets\\Results\\ListPetsResult.cs created\n🟢   src:  Contracts\\Pets\\Results\\CreatePetsResult.cs created\n🟢   src:  Contracts\\Pets\\Results\\ShowPetByIdResult.cs created\n🟢   src:  Contracts\\Pets\\Interfaces\\IListPetsHandler.cs created\n🟢   src:  Contracts\\Pets\\Interfaces\\ICreatePetsHandler.cs created\n🟢   src:  Contracts\\Pets\\Interfaces\\IShowPetByIdHandler.cs created\n🟢   src:  Endpoints\\PetsController.cs created\n🔷 Working on server domain generation (PetStore.Domain)\n🟢   src:  PetStore.Domain.csproj created\n🟢   src:  DomainRegistration.cs created\n🟢   src:  Handlers\\Pets\\ListPetsHandler.cs created\n🟢   src:  Handlers\\Pets\\CreatePetsHandler.cs created\n🟢   src:  Handlers\\Pets\\ShowPetByIdHandler.cs created\n🔶 Working on server domain unit-test generation (PetStore.Domain.Tests)\n🟢   test: PetStore.Domain.Tests.csproj created\n🟢   test: Handlers\\Pets\\Generated\\ListPetsHandlerGeneratedTests.cs created\n🟢   test: Handlers\\Pets\\ListPetsHandlerTests.cs created\n🟢   test: Handlers\\Pets\\Generated\\CreatePetsHandlerGeneratedTests.cs created\n🟢   test: Handlers\\Pets\\CreatePetsHandlerTests.cs created\n🟢   test: Handlers\\Pets\\Generated\\ShowPetByIdHandlerGeneratedTests.cs created\n🟢   test: Handlers\\Pets\\ShowPetByIdHandlerTests.cs created\n🔷 Working on server host generation (PetStore.Api)\n🟢   src:  PetStore.Api.csproj created\n🟢   src:  Properties\\launchSettings.json created\n🟢   src:  Program.cs created\n🟢   src:  Startup.cs created\n🟢   src:  web.config created\n🟢   src:  ConfigureSwaggerDocOptions.cs created\n🔶 Working on server host unit-test generation (PetStore.Api.Tests)\n🟢   test: PetStore.Api.Tests.csproj created\n🟢   test: WebApiStartupFactory.cs created\n🟢   test: WebApiControllerBaseTest.cs created\n🟢   test: Endpoints\\Pets\\Generated\\ListPetsHandlerStub.cs created\n🟢   test: Endpoints\\Pets\\Generated\\ListPetsTests.cs created\n🟢   test: Endpoints\\Pets\\Generated\\CreatePetsHandlerStub.cs created\n🟢   test: Endpoints\\Pets\\Generated\\CreatePetsTests.cs created\n🟢   test: Endpoints\\Pets\\Generated\\ShowPetByIdHandlerStub.cs created\n🟢   test: Endpoints\\Pets\\Generated\\ShowPetByIdTests.cs created\n🟢   root: PetStore.sln created\n🟢   root: PetStore.sln.DotSettings created\n📐 Working on Coding Rules files\n🟢   root: atc-coding-rules-updater.json created\n🟢   root: atc-coding-rules-updater.ps1 created\n🐭 Working on EditorConfig files\n     Download from: [GitHub] /atc-net/atc-coding-rules/main/distribution/dotnet9/.editorconfig\n     Download time: 27.947 ms\n🟢   root: .editorconfig created\n     Download from: [GitHub] /atc-net/atc-coding-rules/main/distribution/dotnet9/src/.editorconfig\n     Download time: 22.987 ms\n🟢   src: .editorconfig created\n     Download from: [GitHub] /atc-net/atc-coding-rules/main/distribution/dotnet9/test/.editorconfig\n     Download time: 24.465 ms\n🟢   test: .editorconfig created\n🔨 Working on Directory.Build.props files\n     Download from: [GitHub] /atc-net/atc-coding-rules/main/distribution/dotnet9/Directory.Build.props\n     Download time: 20.880 ms\n🟢   root: Directory.Build.props created\n     Download from: [GitHub] /atc-net/atc-coding-rules/main/distribution/dotnet9/src/Directory.Build.props\n     Download time: 48.340 ms\n🟢   src: Directory.Build.props created\n     Download from: [GitHub] /atc-net/atc-coding-rules/main/distribution/dotnet9/test/Directory.Build.props\n     Download time: 29.480 ms\n🟢   test: Directory.Build.props created\n✅ Done\n```\n\nAfter the generator finishes running, the API can be started by executing the following command:\n\n```powershell\ndotnet run --project C:\\PetStore\\src\\PetStore.Api\n```\n\nAnd then open a browser and navigate to the url: [https://localhost:5001/swagger](https://localhost:5001/swagger)\n\n## Security - supporting role-based security and custom authentication-schemes\n\nTo support role-based security and custom authentication-schemes, support is implemented for 3 custom extension tags in OpenApi specifications.\n\n\u003e x-authorize-roles (role array)\n\u003e\n\u003e x-authentication-schemes (auth-scheme array)\n\u003e\n\u003e x-authentication-required (true/false boolean)\n\nAt the root level of the specification the available roles and auth-schemes possible to use in paths (controllers) / path-items (actions/methods) should be specified. These are used to validate against defined roles other places in the specification.\n\n### Roles and authentication-scheme validation\n\nWhen reading the OpenApi specification, a lot of validations are being run against these 3 custom extension tags. E.g. validating that any path/path-item does not have roles and/or auth-schemes defined, which are not defined globally in the specification. Other validations are also in place to ensure that the combination of the 3 new extensions \"tags\" are set correctly.\n\n### Logic for determining `[Authorize]` or `[AllowAnonymous]` attributes\n\nThe 3 extension \"tags\" can be specified at path/path-item levels.\n\nIf all path-items (operations) under a given path all have x-authentication-required set to true, then a [Authorize] header will still be added to the generated controller class. Otherwise [Authorize(Roles=x,y,z)] and [AllowAnonymous] will be applied the necessary places on the actions/methods in the controller.\n\nAuthentication-Schemes and Authorize-Roles defined at path/controller level is taken into consideration when generating [Authorize] attributes for path-item/action/method level.\n\nIf no path-items (operations) under a given path have the x-authentication-required extension set, then no attributes will be generated for that given path/controller. If you want to force e.g [Authorize] or [AllowAnonymous], set the x-authentication-required extension to `true` or `false` respectively.\n\n### Example\n\n\u003e NOTE: Tags, parameters, responses, request-bodies, schemas etc. are removed for brevity, so the references in spec below are not valid - The specification is only illustrating the various places the 3 new extension tags can be applied.\n\n```yaml\ninfo:\n  title: DEMO API\n  description: DEMO API\n  version: v1\n  contact:\n    name: ATC\n  license:\n    name: MIT\nservers:\n  - url: /api/v1\n    description: Api version 1.0\nx-authorize-roles:\n  - api.execute.read\n  - api.execute.write\n  - admin\n  - operator\nx-authentication-schemes:\n  - OpenIddict.Validation.AspNetCore\ntags:\n  - name: DEMO\n    description: ''\npaths:\n  /data-templates:\n    x-authentication-required: true\n    x-authorize-roles: [operator]\n    x-authentication-schemes: [OpenIddict.Validation.AspNetCore]\n    get:\n      summary: Returns a list of the groups data templates\n      operationId: getDataTemplates\n      x-authorize-roles: [admin,operator]\n      x-authentication-schemes: [OpenIddict.Validation.AspNetCore]\n    post:\n      summary: Create a new data template\n      operationId: createDataTemplate\n      x-authentication-required: false\n  '/data-templates/{dataTemplateId}':\n    x-authentication-required: true\n    x-authorize-roles: [operator]\n    get:\n      summary: Returns a specific data template\n      operationId: getDataTemplateById\n      x-authentication-required: true\n      x-authorize-roles: [api.execute.read]\n    delete:\n      summary: Removes a specific data template\n      operationId: deleteDataTemplateById\n    put:\n      summary: Updates a specific data template\n      operationId: updateDataTemplateById\n  '/data-templates/{dataTemplateId}/tags':\n    post:\n      summary: Creates a new data template tag\n      operationId: createDataTemplateTag\n      x-authorize-roles: [api.execute.read]\n    delete:\n      summary: Deletes a data template tag\n      operationId: deleteDataTemplateTag\n      x-authentication-schemes: [OpenIddict.Validation.AspNetCore]\n  '/data-templates/{dataTemplateId}/tags/{dataTemplateTagId}':\n    x-authentication-required: false\n    put:\n      summary: Updates a specific data template tag\n      operationId: updateDataTemplateTagById\ncomponents:\n  schemas: {}\n  requestBodies: {}\n  responses: {}\n  securitySchemes: {}\n```\n\n## OpenApi Snippets\n\n### List of items\n\n```yaml\n# Example with List of items\n/users:\n    get:\n      operationId: getUsers\n      responses:\n        '200':\n          description: OK\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/User'\n```\n\n```csharp\n// Output for result type\nIEnumerable\u003cUser\u003e\n```\n\n### List of items with a custom PaginationResult\n\n```yaml\n # Example with List of items with a custom PaginationResult\n/users:\n    get:\n      operationId: getUsers\n      responses:\n        '200':\n          description: success\n          content:\n            application/json:\n              schema:\n                allOf:\n                  - $ref: '#/components/schemas/PaginatedResult'\n                  - type: object\n                    properties:\n                      results:\n                        type: array\n                        items:\n                            $ref: '#/components/schemas/User'\n```\n\n```csharp\n// Output for result type\nPaginationResult\u003cUser\u003e\n```\n\n### List of items with a built-in Pagination\n\n```yaml\n# Example with List of items with a built-in Pagination\n/users:\n    get:\n      operationId: getUsers\n      responses:\n        '200':\n          description: success\n          content:\n            application/json:\n              schema:\n                allOf:\n                  - $ref: '#/components/schemas/Pagination'\n                  - $ref: '#/components/schemas/User'\n```\n\n```csharp\n// Output for result type\nPagination\u003cUser\u003e\n```\n\n### AsyncEnumerable of items\n\n```yaml\n# Example with AsyncEnumerable of items\n/users:\n    get:\n      operationId: getUsers\n      x-return-async-enumerable: true\n      responses:\n        '200':\n          description: OK\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/User'\n```\n\n```csharp\n// Output for result type\nIAsyncEnumerable\u003cUser\u003e\n```\n\n### AsyncEnumerable of items with a custom PaginationResult\n\n```yaml\n# Example with AsyncEnumerable of items with a custom PaginationResult\n/users:\n    get:\n      operationId: getUsers\n      x-return-async-enumerable: true\n      responses:\n        '200':\n          description: success\n          content:\n            application/json:\n              schema:\n                allOf:\n                  - $ref: '#/components/schemas/PaginatedResult'\n                  - type: object\n                    properties:\n                      results:\n                        type: array\n                        items:\n                            $ref: '#/components/schemas/User'\n```\n\n```csharp\n// Output for result type\nIAsyncEnumerable\u003cPaginationResult\u003cUser\u003e\u003e\n```\n\n### AsyncEnumerable of items with a built-in Pagination\n\n```yaml\n# Example with AsyncEnumerable of items with a built-in Pagination\n# Note: The build-in Pagination can be found in namespace Atc.Rest.Results\n/users:\n    get:\n      operationId: getUsers\n      x-return-async-enumerable: true\n      responses:\n        '200':\n          description: success\n          content:\n            application/json:\n              schema:\n                allOf:\n                  - $ref: '#/components/schemas/Pagination'\n                  - $ref: '#/components/schemas/User'\n```\n\n```csharp\n// Output for result type\nIAsyncEnumerable\u003cPagination\u003cUser\u003e\u003e\n```\n\n### Custom PaginationResult with query parameters\n\n```yaml\n # Example with custom PaginationResult and use of query parameters\npaths:\n  /users:\n    get:\n      operationId: getUsers\n      parameters:\n        - $ref: '#/components/parameters/pageSize'\n        - $ref: '#/components/parameters/continuationToken'\n        - $ref: '#/components/parameters/queryString'\n      responses:\n        '200':\n          description: success\n          content:\n            application/json:\n              schema:\n                allOf:\n                  - $ref: '#/components/schemas/PaginationResult'\n                  - type: object\n                    properties:\n                      results:\n                        type: array\n                        items:\n                          $ref: '#/components/schemas/User'\ncomponents:\n  schemas:\n    PaginationResult:\n      type: object\n      title: PaginationResult\n      description: An item result subset of a data query.\n      properties:\n        pageSize:\n          type: integer\n        continuationToken:\n          type: string\n          nullable: true\n          description: Token to indicate next result set.\n        items:\n          type: array\n          items: {}\n  parameters:\n    pageSize:\n      name: pageSize\n      in: query\n      required: true\n      schema:\n        type: integer\n        default: 10\n    continuationToken:\n      name: continuationToken\n      in: query\n      required: false\n      schema:\n        type: string\n        nullable: true\n    queryString:\n      name: queryString\n      in: query\n      required: true\n      schema:\n        type: string\n```\n\n```csharp\n// Output for generated parameter class in Minimal-Api\npublic record GetUsersParameters(\n    [property: FromQuery] string? ContinuationToken,\n    [property: FromQuery, Required] string QueryString,\n    [property: FromQuery, Required] int PageSize = 10);\n\n\n// Output for generated result class in Minimal-Api\npublic class GetUsersResult\n{\n    private GetUsersResult(IResult result)\n    {\n        Result = result;\n    }\n\n    public IResult Result { get; }\n\n    /// \u003csummary\u003e\n    /// 200 - Ok response.\n    /// \u003c/summary\u003e\n    public static GetUsersResult Ok(PaginationResult\u003cUser\u003e result)\n        =\u003e new(TypedResults.Ok(result));\n\n    /// \u003csummary\u003e\n    /// Performs an implicit conversion from GetUsersResult to IResult.\n    /// \u003c/summary\u003e\n    public static IResult ToIResult(GetUsersResult result)\n        =\u003e result.Result;\n}\n```\n\n## How to contribute\n\n[Contribution Guidelines](https://atc-net.github.io/introduction/about-atc#how-to-contribute)\n\n[Coding Guidelines](https://atc-net.github.io/introduction/about-atc#coding-guidelines)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatc-net%2Fatc-rest-api-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatc-net%2Fatc-rest-api-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatc-net%2Fatc-rest-api-generator/lists"}