如何使用 ASP.NET 构建 RESTful API-JavaScript中文网-JavaScript教程资源分享门户

RESTful API 是一种常见的 API 架构风格，以资源为中心，使用 HTTP 方法进行操作，并且以 JSON 格式交换数据。ASP.NET 是一种跨平台、高性能的 Web 开发框架，我们可以使用 ASP.NET 来构建 RESTful API。

本文将详细介绍如何使用 ASP.NET 构建 RESTful API，包括如何设计 API 路由、如何定义 API 操作、如何使用 Entity Framework Core 连接数据库并进行 CRUD 操作，以及如何使用 Swagger 手动编写 API 文档。

设计 API 路由

RESTful API 的核心是资源和 URL，设计好 URL 是非常重要的一步。在 ASP.NET 中，我们使用路由来定义 URL。对于 RESTful API，我们可以按照 RESTful URL 设计准则来设计 URL。比如，假设我们要设计一个简单的文章管理 API，我们可以将文章资源定义为 /api/articles/{id}，其中 {id} 是文章的唯一标识符。

// www.javascriptcn.com code example
[Route("api/[controller]")]
[ApiController]
public class ArticlesController : ControllerBase
{
    private readonly ApplicationDbContext _db;
    
    public ArticlesController(ApplicationDbContext db)
    {
        _db = db;
    }
    
    // GET: api/articles
    [HttpGet]
    public async Task<ActionResult<IEnumerable<Article>>> Get()
    {
        return await _db.Articles.ToListAsync();
    }
    
    // GET: api/articles/5
    [HttpGet("{id}")]
    public async Task<ActionResult<Article>> Get(int id)
    {
        var article = await _db.Articles.FindAsync(id);
        if (article == null)
        {
            return NotFound();
        }
        return article;
    }
    
    // POST: api/articles
    [HttpPost]
    public async Task<ActionResult<Article>> Post(Article article)
    {
        _db.Articles.Add(article);
        await _db.SaveChangesAsync();
        return CreatedAtAction(nameof(Get), new { id = article.Id }, article);
    }
    
    // PUT: api/articles/5
    [HttpPut("{id}")]
    public async Task<IActionResult> Put(int id, Article article)
    {
        if (id != article.Id)
        {
            return BadRequest();
        }
        _db.Entry(article).State = EntityState.Modified;
        await _db.SaveChangesAsync();
        return NoContent();
    }
    
    // DELETE: api/articles/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> Delete(int id)
    {
        var article = await _db.Articles.FindAsync(id);
        if (article == null)
        {
            return NotFound();
        }
        _db.Articles.Remove(article);
        await _db.SaveChangesAsync();
        return NoContent();
    }
}

定义 API 操作

RESTful API 的五种 HTTP 方法对应着五种操作：获取资源列表（GET）、获取单个资源（GET）、创建资源（POST）、更新资源（PUT）和删除资源（DELETE）。在 ASP.NET 中，我们可以使用控制器来定义这些操作。控制器中的方法必须加上 [HttpGet]、[HttpPost]、[HttpPut] 或者 [HttpDelete] 等标记，以指示它对应的 HTTP 方法。

比如，我们可以定义一个 GET 方法来获取文章列表：

[HttpGet]
public async Task<ActionResult<IEnumerable<Article>>> Get()
{
    return await _db.Articles.ToListAsync();
}

这个方法使用了异步操作，它会从数据库中获取所有文章并返回 JSON 格式的列表。

我们还可以定义一个 POST 方法来创建文章：

[HttpPost]
public async Task<ActionResult<Article>> Post(Article article)
{
    _db.Articles.Add(article);
    await _db.SaveChangesAsync();
    return CreatedAtAction(nameof(Get), new { id = article.Id }, article);
}

这个方法获取一个 Article 对象作为参数，将文章添加到数据库中，最后返回 201 Created 状态码和新文章的详细信息。

其他的方法根据同样的方式定义。

使用 Entity Framework Core 连接数据库并进行 CRUD 操作

在 ASP.NET 中，我们可以使用 Entity Framework Core 来连接数据库，并进行 CRUD 操作。Entity Framework Core 是一个轻量级、跨平台、开源的 ORM（Object-Relational Mapping）框架，它可以将数据库中的数据映射到 C# 对象中。我们可以使用它来快速构建 RESTful API。

在 ASP.NET 中，我们需要先定义一个 DbContext 类来表示数据库的上下文。这个类继承自 DbContext 类，我们需要在构造函数中传入 DbContextOptions 对象，以指定数据库的连接字符串。

比如，假设我们要连接一个名为 MyDatabase 的 SQLite 数据库，我们需要定义一个 ApplicationDbContext 类，继承自 DbContext 类，并通过 UseSqlite 方法指定数据库连接字符串：

// www.javascriptcn.com code example
public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
    }
    
    public DbSet<Article> Articles { get; set; }
    
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Article>().ToTable("Articles");
    }
}

这个类有一个名为 Articles 的 DbSet 属性，表示文章表。我们需要在 OnModelCreating 方法中调用 ToTable 方法指定表名为 Articles。

然后，在 Startup.cs 文件的 ConfigureServices 方法中注册 ApplicationDbContext：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlite(Configuration.GetConnectionString("DefaultConnection")));
        
    services.AddControllers();
}

这个方法使用了 AddDbContext 扩展方法，将 ApplicationDbContext 注册到依赖注入容器中，并指定连接字符串为 DefaultConnection。

最后，在控制器中注入 ApplicationDbContext 实例，并使用它来进行 CRUD 操作：

// www.javascriptcn.com code example
private readonly ApplicationDbContext _db;

public ArticlesController(ApplicationDbContext db)
{
    _db = db;
}

// GET: api/articles
[HttpGet]
public async Task<ActionResult<IEnumerable<Article>>> Get()
{
    return await _db.Articles.ToListAsync();
}

// GET: api/articles/5
[HttpGet("{id}")]
public async Task<ActionResult<Article>> Get(int id)
{
    var article = await _db.Articles.FindAsync(id);
    if (article == null)
    {
        return NotFound();
    }
    return article;
}

// POST: api/articles
[HttpPost]
public async Task<ActionResult<Article>> Post(Article article)
{
    _db.Articles.Add(article);
    await _db.SaveChangesAsync();
    return CreatedAtAction(nameof(Get), new { id = article.Id }, article);
}

// PUT: api/articles/5
[HttpPut("{id}")]
public async Task<IActionResult> Put(int id, Article article)
{
    if (id != article.Id)
    {
        return BadRequest();
    }
    _db.Entry(article).State = EntityState.Modified;
    await _db.SaveChangesAsync();
    return NoContent();
}

// DELETE: api/articles/5
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(int id)
{
    var article = await _db.Articles.FindAsync(id);
    if (article == null)
    {
        return NotFound();
    }
    _db.Articles.Remove(article);
    await _db.SaveChangesAsync();
    return NoContent();
}

使用 Swagger 手动编写 API 文档

API 文档是 RESTful API 的重要组成部分，它描述了 API 的接口、参数、返回值等信息。在 ASP.NET 中，我们可以使用 Swagger 来编写和生成 API 文档。Swagger 是一种开源的 API 文档工具，可以自动生成 API 的客户端库、API 测试代码等。

我们可以使用 Swagger UI 来查看和测试 API 文档。模板代码已经包含了 Swagger 的依赖项，我们只需要在 Startup.cs 文件中启用 Swagger 并生成 API 文档即可。

首先，我们需要使用 Swashbuckle.AspNetCore 将 Swagger 集成到 ASP.NET 中。在 Startup.cs 文件的 ConfigureServices 方法中添加以下代码：

// www.javascriptcn.com code example
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
    
    services.AddControllers();
}

这里使用了 AddSwaggerGen 扩展方法，指定了 API 的版本和标题等信息。

然后，在 Startup.cs 文件的 Configure 方法中添加以下代码：

// www.javascriptcn.com code example
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
    
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    
    app.UseRouting();
    
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

这里使用了 UseSwagger 和 UseSwaggerUI 方法来启用 Swagger，指定了 API 的终端节点和 API 的版本等信息。

最后，在控制器中添加 Swagger 标记来编写 API 文档。比如，我们可以使用 SwaggerOperation 来描述 API 操作的摘要和详细说明：

[HttpGet("{id}")]
[SwaggerOperation(Summary = "Get an article by ID")]
public async Task<ActionResult<Article>> Get(int id)
{
    // ...
}

使用 Swagger 可以帮助我们方便地编写和维护 API 文档，减少错误和手动工作，提高开发效率。

结语

本文详细介绍了如何使用 ASP.NET 构建 RESTful API，包括如何设计 API 路由、如何定义 API 操作、如何使用 Entity Framework Core 连接数据库并进行 CRUD 操作，以及如何使用 Swagger 手动编写 API 文档。RESTful API 是一种常见的 API 架构风格，可以使 API 更加灵活、可扩展和易于维护。ASP.NET 是一个跨平台、高性能的 Web 开发框架，可以帮助我们快速构建 RESTful API，并且支持开箱即用的 Swagger 集成，方便我们编写和维护 API 文档。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/67c55ab76e1fc40e36ee9125

如何使用 ASP.NET 构建 RESTful API

设计 API 路由

定义 API 操作

使用 Entity Framework Core 连接数据库并进行 CRUD 操作

使用 Swagger 手动编写 API 文档

结语

接着读