在现代Web应用的开发中，Azure平台即服务（PaaS）提供了一个强大的托管环境，不仅能够执行应用逻辑，还提供了一整套健壮的机制来管理Web应用的生命周期。这些关键特性对于通过Azure云创建现代Web应用至关重要。
在设计基于Web应用的软件架构时，需要实现一个API层，以便架构中的各个层能够相互通信。无论应用架构如何，这都是一个实现RESTful API的好机会，并且可以为API的使用提供相应的文档。
在Azure App Service中创建RESTful API应用有多种方法，最常见的是通过Azure门户或直接从Visual Studio进行。以下是一个使用Visual Studio 2019的示例：
这样，Visual Studio就会创建一个新的Web API项目，并在解决方案资源管理器的文件树中生成以下文件结构：
Swashbuckle是一个非常流行的开源框架，由一系列工具组成，用于设计、构建、文档化和消费RESTful API。它是创建API文档的理想选择，NuGet包非常详细地记录了文档，可以通过访问文章末尾的GitHub项目来查看更多详细信息。
Swashbuckle通过一组NuGet包提供：Swashbuckle和Swashbuckle Core。按照以下步骤将Swashbuckle添加到API项目中：
Install-Package Swashbuckle
NuGet包还安装了一个初始引导文件或引导程序（App_Start / SwaggerConfig.cs），它使用WebActivatorEx在启动API应用程序时启用Swagger路径。还可以通过修改SwaggerConfig.cs文件中的GlobalConfiguration.Configuration.EnableSwagger扩展方法来配置Swashbuckle选项。还可以排除已用过时装饰标记的API操作，添加以下配置：
public class SwaggerConfig {
public static void Register() {
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration.EnableSwagger(c => {
...
...
// 设置此标志以省略已用Obsolete属性装饰的任何类型属性的模式属性描述
c.IgnoreObsoleteProperties();
...
...
});
}
}
修改API项目中的控制器操作，以包含swagger属性，以帮助生成器构建swagger元数据。
现在，Swashbuckle已配置为使用简单的用户界面为API端点生成Swagger元数据，可以通过在Web浏览器地址栏中输入Swagger来查看列出的metadata.controller生成的UI。
到目前为止，已经设计了一个API，它具有与项目其他层连接的基本功能，还生成了一个自动文档，充分利用了所有通过其控制器操作定义的API的元数据和定义。已经准备好了上述内容，需要完成从Visual Studio到Azure App Service的发布，以在云中部署API项目。
一旦整个API项目环境在Azure App Service中配置完毕，Visual Studio就会创建一个发布配置文件，以便每次想要运行带有新更改的API部署时，只需运行发布按钮即可。Visual Studio会编译并尝试上传API项目的所有文件到Azure云通过Azure App service，所以现在可以通过互联网访问其API。
当API项目发布完成后，它将在一个新的浏览器窗口中打开，显示初始发布网页。
将导航到Swagger文档通过/Swagger路由查看API文档的详细信息，以及测试已经通过API暴露的REST方法。例如，http://<YOUR-API-APP>.azurewebsites.net/swagger/。
通过这种方式，已经可以在Azure云通过Azure App Service运行一个结构良好的RESTful应用程序，并自动生成文档。
通过这种方式，可以在Azure云中以更有序、清晰的方式发布API，并为API项目的良好管理维护提供强大的文档支持。
很高兴在评论中看到任何其他示例（真实或仅想法），无论是API文档的良好使用案例，还是Microsoft Azure云支持的软件开发的其他案例。