API标准规范 - Swagger

Swagger 是最早出现的、最成熟的API标准规范。已经改名为 OpenAPI Specification。官网是 https://swagger.io/。最新发布的是3.0.0版本，也是使用YAML格式对API的界面定义进行编辑，并提供了直观的工具，如API设计器和API控制台。

http://editor.swagger.io

当然一开始就采用YAML格式编写API定义文档，难度确实不小。并且很多情况下，都是开发人员调查个草稿，然后直接进行编码开发，之后再给调用人员提供详细的API技术文档。

解决现有程序API文档问题

在调用其他人编写的Web API时，了解其各种方法对于开发人员来说可能是一项挑战。
还好Swagger提供一些帮助，比如在dotnet core 中可以通过安装第三方的程序集解决现有API的文档问题，通过一套反射机制从代码中生成文档，并且借助ajax可以直接在文档中对API进行交互。因为代码与文档是捆绑的所以在迭代代码的时候，就能方便的将文档也更新了。不会出现随着项目推移代码与文档不匹配的问题。

比如我的 asp.net core 项目地址：http://localhost:5003，那么就可以访问 http://localhost:5003/swagger就可以进入到API文档控制台

swagger ui

可以在swagger UI 进行测试

测试API

上面的UI界面上元素都是来源于http://localhost:5003/swagger/v1/swagger.json 中API文档描述,
这是一个JSON格式的描述。虽然格式上不同于 swaggereditor采用YAML格式，但是标准上是一样的。

{

  "x-generator": "NSwag v12.0.18.0 (NJsonSchema v9.13.27.0 (Newtonsoft.Json v11.0.0.0))",
  "swagger": "2.0",
  "info": {
    "title": "My Title",
    "version": "1.0.0"
  },
  "host": "localhost:5003",
  "schemes": [
    "http"
  ],
  "paths": {
    "/Identity": {
      "get": {
        "tags": [
          "Identity"
        ],
        "summary": "读取当前登录人的个人信息",
        "operationId": "Identity_Index",
        "responses": {
          "200": {
            "x-nullable": true,
            "description": "",
            "schema": {
              "type": "file"
            }
          }
        }
      }
    },
    "/Identity/Access_Token": {
      "get": {
        "tags": [
          "Identity"
        ],
        "summary": "获得访问票据",
        "operationId": "Identity_Access_Token",
        "responses": {
          "200": {
            "x-nullable": true,
            "description": "",
            "schema": {
              "type": "file"
            }
          }
        }
      }
    }
  }
}

• 参考：
  现代API:通往架构师之门

Test Your ASP.NET Core Web API With Swagger
ASP.NET Core web API help pages with Swagger / OpenAPI