diff --git a/README.md b/README.md index 81df487e..bda47c5f 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ Work on the current version of the protocol (V4) began in April 2012, and was ra Coming Soon! ## Supported Platforms -Restier 1.0 currently supports the following platforms: +Restier 1.1 currently supports the following platforms: - Classic ASP.NET 5.2.7 and later - ASP.NET Core 6.0, 7.0, and 8.0 (Binaries targeting deprecated versions of .NET are still available on NuGet.org) - Entity Framework 6.4 and later @@ -54,22 +54,21 @@ Restier is made up of the following components: - **Microsoft.Restier.AspNet & Microsoft.Restier.AspNetCore:** Plugs into the OData/WebApi processing pipeline and provides query interception capabilities. - **Microsoft.Restier.Core:** The base library that contains the core convention-based interception framework. - **Microsoft.Restier.EntityFramework & Microsoft.Restier.EntityFramework:** Translates intercepted queries down to the database level to be executed. -- **Microsoft.Restier.Breakdance:** Unit test Restier services and components in-memory without spnning up a separate IIS instance, as well as verify the availability of your custom convention-based interceptors. +- **Microsoft.Restier.Breakdance:** Unit test Restier services and components in-memory without spinning up a separate IIS instance, as well as verify the availability of your custom convention-based interceptors. +- **Microsoft.Restier.AspNetCore.Swagger:** Automatically generates Swagger documentation for your ASP.NET Core Restier service. ## Ecosystem Restier is used in solutions from: - [BurnRate.io](https://burnrate.io) -- [CloudNimble, Inc.](https://nimbleapps.cloud) +- [CloudNimble](https://nimbleapps.cloud) - [Florida Agency for Health Care Administration](https://ahca.myflorida.com) +- [Microsoft](https://graph.microsoft.com) - [Miller's Ale House](https://millersalehouse.com) +- [NoCore](https://nocore.nl) ## Community After a couple years in statis, Restier is in active development once again. The project is lead by Robert McLaws and Mike Pizzo. -### Weekly Standups -The core development team meets twice a month on Microsoft Teams to discuss pressing items and work through the issues list. A history of -those meetings can be found in the Wiki. - ### Contributing If you'd like to help out with the project, our Contributor's Handbook is also located in the Wiki. @@ -79,7 +78,7 @@ Security issues and bugs should be reported privately, via email, to the Microso ## Contributors -Special thanks to everyone involved in making RESTier the best API development platform for .NET. The following people +Special thanks to everyone involved in making Restier the best API development platform for .NET. The following people have made various contributions to the codebase: | Microsoft | External | @@ -90,9 +89,9 @@ have made various contributions to the codebase: | Vincent He | Kemal M | | Dong Liu | Mateusz Malicki | | Layla Liu | Robert McLaws | -| Fan Ouyang | Jan-Willem Spuij | -| Mike Pizzo | Chris Woodruff | -| Congyong S | | +| Fan Ouyang | Micah Rairdon | +| Mike Pizzo | Jan-Willem Spuij | +| Congyong S | Chris Woodruff | | Mark Stafford | | | Ray Yao | | diff --git a/src/Microsoft.Restier.AspNetCore.Swagger/Microsoft.Restier.AspNetCore.Swagger.csproj b/src/Microsoft.Restier.AspNetCore.Swagger/Microsoft.Restier.AspNetCore.Swagger.csproj index f8dfeeb4..5587656a 100644 --- a/src/Microsoft.Restier.AspNetCore.Swagger/Microsoft.Restier.AspNetCore.Swagger.csproj +++ b/src/Microsoft.Restier.AspNetCore.Swagger/Microsoft.Restier.AspNetCore.Swagger.csproj @@ -4,6 +4,7 @@ net8.0;net7.0;net6.0; $(StrongNamePublicKey) $(DocumentationFile)\$(AssemblyName).xml + README.md @@ -17,4 +18,10 @@ + + + PreserveNewest + + + diff --git a/src/Microsoft.Restier.AspNetCore.Swagger/README.md b/src/Microsoft.Restier.AspNetCore.Swagger/README.md new file mode 100644 index 00000000..fb88b346 --- /dev/null +++ b/src/Microsoft.Restier.AspNetCore.Swagger/README.md @@ -0,0 +1,104 @@ +# Microsoft Restier - OData Made Simple + +[Releases](https://github.com/OData/RESTier/releases)   |   Documentation   |   [OData v4.01 Documentation](https://www.odata.org/documentation/) + + + +## Swagger for Restier ASP.NET Core + +This package helps you quickly implement OpenAPI's Swagger.json and Swagger UI in your Restier service in just a few lines of code. + +## Supported Platforms +[Microsoft.Restier.AspNetCore.Swagger](https://www.nuget.org/packages/Microsoft.Restier.AspNetCore.Swagger) 1.1 currently supports the following platforms: +- ASP.NET Core 6.0, 7.0, and 8.0 via Endpoint Routing + +## Getting Started +Building OpenAPI into your Restier project is easy! + +### Step 1: Install [Microsoft.Restier.AspNetCore.Swagger](https://www.nuget.org/packages/Microsoft.Restier.AspNetCore.Swagger/1.1.0-CI-20231125-225528) +- Add the package above to your API project. +- **[Optional]** Change the version of your Restier packages to `1.*-*` so you always get the latest version. + +### Step 2: Convert to Endpoint Routing (Part 1) +- Add the new parameter to the end of your `services.AddRestier()` call: +```cs + services.AddRestier((builder) => + { + ... + }, true); // <-- @robertmclaws: This parameter adds Endpoint Routing support. +``` + +### Step 3: Register Swagger Services +- Add the line below immediately after the `services.AddRestier()` call: +```cs +services.AddRestierSwagger(); +``` +- There is an overload to this method that takes an `Action` that will let you change the configuration of the generated Swagger definition. + +### Step 4: Convert to Endpoint Routing & Use Swagger (Part 2) +- Replace your existing `Configure` code with the following (don't forget your customizations): +```cs + public void Configure(IApplicationBuilder app, IWebHostEnvironment env) + { + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + + app.UseRestierBatching(); + app.UseRouting(); + + app.UseAuthorization(); + // @robertmclaws: This line is optional but helps with leveraging ClaimsPrincipal.Current for cross-platform business logic. + app.UseClaimsPrincipals(); + + app.UseEndpoints(endpoints => + { + endpoints.Select().Expand().Filter().OrderBy().MaxTop(100).Count().SetTimeZoneInfo(TimeZoneInfo.Utc); + endpoints.MapRestier(builder => + { + builder.MapApiRoute("ROUTENAME", "ROUTEPREFIX", true); + }); + }); + + app.UseRestierSwagger(true); + } +``` +- On the last line, the boolean specifies whether or not to use SwaggerUI. If you want to control more of the UI configuration, use `services.Configure();` in your `ConfigureServices()` method. + +### Step 5: Browse Swagger Resources +- Browse to `/swagger/ROUTENAME/swagger.json` to see the generated Swagger definition. +- Browse to `/swagger` to see the Swagger UI. + +## Reporting Security Issues + +Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) . You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue). You can also find these instructions in this repo's [SECURITY.md](./SECURITY.md). + +## Contributors + +Special thanks to everyone involved in making Restier the best API development platform for .NET. The following people have made various contributions to this package: + +| External | +|------------------| +| Cengiz Ilerler | +| Robert McLaws | +| Micah Rairdon | + + + +[devops-build]:https://dev.azure.com/dotnet/OData/_build?definitionId=89 +[devops-release]:https://dev.azure.com/dotnet/odata/_release?view=all&definitionId=2 +[twitter-intent]:https://twitter.com/intent/tweet?url=https%3A%2F%2Fgithub.com%2FOData%2FRESTier&via=robertmclaws&text=Check%20out%20Restier%21%20It%27s%20the%20simple%2C%20queryable%20framework%20for%20building%20data-driven%20APIs%20in%20.NET%21&hashtags=odata +[code-of-conduct]:https://opensource.microsoft.com/codeofconduct/ + +[devops-build-img]:https://img.shields.io/azure-devops/build/dotnet/odata/89.svg?style=for-the-badge&logo=azuredevops +[devops-release-img]:https://img.shields.io/azure-devops/release/dotnet/f69f4a5b-2486-494e-ad83-7ba2b889f752/2/2.svg?style=for-the-badge&logo=azuredevops +[nightly-feed-img]:https://img.shields.io/badge/continuous%20integration-feed-0495dc.svg?style=for-the-badge&logo=nuget&logoColor=fff +[github-version-img]:https://img.shields.io/github/release/ryanoasis/nerd-fonts.svg?style=for-the-badge +[gitter-img]:https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=for-the-badge +[code-climate-img]:https://img.shields.io/codeclimate/issues/github/ryanoasis/nerd-fonts.svg?style=for-the-badge +[code-of-conduct-img]: https://img.shields.io/badge/code%20of-conduct-00a1f1.svg?style=for-the-badge&logo=windows +[twitter-img]:https://img.shields.io/badge/share-on%20twitter-55acee.svg?style=for-the-badge&logo=twitter diff --git a/src/RESTier.sln b/src/RESTier.sln index d542c852..90c46031 100644 --- a/src/RESTier.sln +++ b/src/RESTier.sln @@ -29,7 +29,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Directory.Build.props = Directory.Build.props dotnet-logo.png = dotnet-logo.png global.json = global.json - README.md = README.md + ..\README.md = ..\README.md EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "Samples", "{DB42E0B8-C0C7-4DE4-9437-2B2A229B5F8F}"