iT邦幫忙

第 11 屆 iThome 鐵人賽

DAY 14
0
DevOps

.NET Core 專案持續整合與部署系列 第 14

Integrate:API Documents

  • 分享至 

  • xImage
  •  
$ 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": { }
}

上一篇
Integrate:Version Number
下一篇
Virtualize:透過 Docker 建置 .NET Core 專案
系列文
.NET Core 專案持續整合與部署31
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言