$ dotnet new webapi -o APIProj
The template "ASP.NET Core Web API" was created successfully.
Processing post-creation actions...
Running 'dotnet restore' on APIProj/APIProj.csproj...
Restore completed in 1.39 sec for /Users/ironman/dotnet-sln/APIProj/APIProj.csproj.
Restore succeeded.
$ cd APIProj
$ dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.0.0-rc3
Writing /var/folders/hx/lgdjx1l93pq08s35hhwb0py40000gn/T/tmpe2fBFb.tmp
info : Adding PackageReference for package 'Swashbuckle.AspNetCore' into project '/Users/ironman/dotnet-sln/APIProj/APIProj.csproj'.
info : Restoring packages for /Users/ironman/dotnet-sln/APIProj/APIProj.csproj...
info : GET https://api.nuget.org/v3-flatcontainer/swashbuckle.aspnetcore/index.json
info : OK https://api.nuget.org/v3-flatcontainer/swashbuckle.aspnetcore/index.json 955ms
.......
info : Installing Microsoft.AspNetCore.Http.Features 2.0.0.
info : Installing Microsoft.AspNetCore.Authentication.Abstractions 2.0.0.
info : Installing Microsoft.AspNetCore.Authorization 2.0.0.
info : Installing Microsoft.AspNetCore.WebUtilities 2.0.0.
info : Installing Microsoft.DotNet.PlatformAbstractions 2.0.0.
info : Installing Microsoft.Extensions.Localization.Abstractions 2.0.0.
info : Installing Microsoft.CSharp 4.4.0.
info : Installing Microsoft.Extensions.Hosting.Abstractions 2.0.0.
info : Installing Microsoft.AspNetCore.Hosting.Server.Abstractions 2.0.0.
info : Installing Microsoft.AspNetCore.Http.Abstractions 2.0.0.
info : Installing Microsoft.Net.Http.Headers 2.0.0.
info : Installing System.Text.Encodings.Web 4.4.0.
info : Installing Microsoft.Extensions.DependencyInjection.Abstractions 2.0.0.
info : Installing Microsoft.AspNetCore.Mvc.Abstractions 2.0.0.
info : Installing Microsoft.AspNetCore.Authentication.Core 2.0.0.
info : Installing Microsoft.AspNetCore.Authorization.Policy 2.0.0.
info : Installing Swashbuckle.AspNetCore 5.0.0-rc3.
info : Installing Swashbuckle.AspNetCore.Swagger 5.0.0-rc3.
info : Installing Swashbuckle.AspNetCore.SwaggerGen 5.0.0-rc3.
info : Installing Microsoft.Extensions.FileProviders.Embedded 2.0.0.
info : Installing Microsoft.AspNetCore.Http 2.0.0.
info : Installing Microsoft.Extensions.ApiDescription.Server 0.3.0-preview7.19365.7.
info : Installing Swashbuckle.AspNetCore.SwaggerUI 5.0.0-rc3.
info : Installing Microsoft.AspNetCore.StaticFiles 2.0.0.
info : Installing Microsoft.AspNetCore.Routing 2.0.0.
info : Installing Microsoft.AspNetCore.Mvc.ApiExplorer 2.0.0.
info : Installing Microsoft.OpenApi 1.1.1.
info : Installing Microsoft.Extensions.DependencyModel 2.0.0.
info : Installing Microsoft.AspNetCore.Mvc.Formatters.Json 2.0.0.
info : Installing Microsoft.AspNetCore.Mvc.DataAnnotations 2.0.0.
info : Installing Microsoft.AspNetCore.Mvc.Core 2.0.0.
info : Installing System.Diagnostics.DiagnosticSource 4.4.1.
info : Installing Microsoft.Extensions.Logging.Abstractions 2.0.0.
info : Installing Microsoft.Extensions.WebEncoders 2.0.0.
info : Installing Microsoft.AspNetCore.Http.Extensions 2.0.0.
info : Installing Microsoft.AspNetCore.Hosting.Abstractions 2.0.0.
info : Installing Microsoft.Extensions.Options 2.0.0.
info : Installing Microsoft.Extensions.ObjectPool 2.0.0.
info : Installing Microsoft.AspNetCore.Routing.Abstractions 2.0.0.
info : Installing Microsoft.AspNetCore.JsonPatch 2.0.0.
info : Installing System.ComponentModel.Annotations 4.4.0.
info : Installing Microsoft.Extensions.Localization 2.0.0.
info : Installing Microsoft.AspNetCore.ResponseCaching.Abstractions 2.0.0.
info : Package 'Swashbuckle.AspNetCore' is compatible with all the specified frameworks in project '/Users/ironman/dotnet-sln/APIProj/APIProj.csproj'.
info : PackageReference for package 'Swashbuckle.AspNetCore' version '5.0.0-rc3' added to file '/Users/ironman/dotnet-sln/APIProj/APIProj.csproj'.
info : Committing restore...
info : Generating MSBuild file /Users/ironman/dotnet-sln/APIProj/obj/APIProj.csproj.nuget.g.props.
info : Generating MSBuild file /Users/ironman/dotnet-sln/APIProj/obj/APIProj.csproj.nuget.g.targets.
info : Writing assets file to disk. Path: /Users/ironman/dotnet-sln/APIProj/obj/project.assets.json
log : Restore completed in 31.04 sec for /Users/ironman/dotnet-sln/APIProj/APIProj.csproj.
接著在 Startup.cs
中,
加入參考:
// ....
using Microsoft.OpenApi.Models;
在 ConfigureServices()
中註冊產生器:
public void ConfigureServices(IServiceCollection services)
{
// ....
// Register Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
}
在 Configure()
中啟用 route 去顯示 Swagger 的 JSON 檔案:
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
// ...
}
最後,執行看看:
$ dotnet run
Hosting environment: Development
Content root path: /Users/ironman/dotnet-sln/APIProj
Now listening on: https://localhost:5001
Now listening on: http://localhost:5000
就會在 https://localhost:5001/swagger/v1/swagger.json 看到:
{
"openapi": "3.0.1",
"info": {
"title": "My API",
"version": "v1"
},
"paths": {
"/api/Values": {
"get": {
"tags": [
"Values"
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"post": {
"tags": [
"Values"
],
"requestBody": {
"content": {
"application/json-patch+json": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
},
"application/*+json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "Success"
}
}
}
},
"/api/Values/{id}": {
"get": {
"tags": [
"Values"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
}
}
}
}
},
"put": {
"tags": [
"Values"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json-patch+json": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
},
"application/*+json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "Success"
}
}
},
"delete": {
"tags": [
"Values"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Success"
}
}
}
}
},
"components": { }
}