swagger api 之（一）

最新推荐文章于 2025-07-06 17:44:02 发布

脾气很倔呢

最新推荐文章于 2025-07-06 17:44:02 发布

阅读量5.1k

点赞数

CC 4.0 BY-SA版权

分类专栏： spring-boot swagger 文章标签： spring-boot

本文链接：https://blog.youkuaiyun.com/expect521/article/details/77507192

spring-boot 同时被 2 个专栏收录

20 篇文章

订阅专栏

swagger

7 篇文章

订阅专栏

本文档介绍了如何使用Spring Boot、Swagger构建一个包含用户增删改查操作的RESTful API，并生成对应的API文档。通过Swagger注解详细解释了如何定义URL路径、处理HTTP请求方法以及返回JSON响应。提供了代码片段和访问URL以供参考。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

功能

生成一个swagger api文档，内容是对用户增删改查的操作，返回数据格式是json。用的是restful风格。例如：

这里写图片描述

技术与IDE

spring boot
IntelliJ IDEA
maven
swagger

代码参考github：

Swagger-Restful-Api

代码片段

UserService.java

@RestController
@RequestMapping(value = "/user")
public class UserService {

    @Autowired
    private UserReponsitory userReponsitory;

    /**
     * @Function get all users(getUsers())
     * @Get
     * @url ""
     * @param no
     * @return List<User></>
     */
    @ApiOperation(value = "获取用户列表",notes = "获取所有的用户的详细信息")
    @RequestMapping(value = "/users",method = RequestMethod.GET)
    public List<User> getUsers(){
        List<User> users =   userReponsitory.getUsers();
        return users;
    }


    /**
     * @Function get one user(getUser())
     * @Get
     * @url "/{id}"
     * @param (Long id)
     * @return User
     */
    @ApiOperation(value = "获取用户详细信息",notes = "根据url的id来获取用户的详细信息")
    @ApiImplicitParam(name = "id",value = "用户ID",required = true,dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.GET)
    public User getUser(@PathVariable int id){
        User user = userReponsitory.getUser(id);
        return user;
    }


    /**
     * @Function post one user (postUser())
     * @POST
     * @url ""
     * @param User user
     * @return  SUCCESS
     */
    @ApiOperation(value = "创建用户",notes = "根据User对象创建用户")
    @ApiImplicitParam(name = "user",value = "用户详细实体user",required = true,dataType = "User")
    @RequestMapping(value = "",method = RequestMethod.POST)
    public String postUser(@RequestBody User user){
       String returnMessage = userReponsitory.postUser(user);
       return returnMessage;
    }

    /**
     * @Function put one user(putUser())
     * @PUT
     * @url "/{id}"
     * @param (Long id,User user)
     * @return SUCCESS
     */
    @ApiOperation(value = "更新用户的信息",notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户ID",required = true,dataType = "Long"),
            @ApiImplicitParam(name = "user",value = "用户详细实体user",required = true,dataType = "User")
    })
    @RequestMapping(value = "/{id}",method = RequestMethod.PUT)
    public String putUser(@PathVariable int id,@RequestBody User user){
        String returnMessage = userReponsitory.putUser(id,user);
        return returnMessage;
    }

    /**
     * @Function delete one user(deleteUser())
     * @DELETE
     * @url "/{id}"
     * @param (Long id)
     * @return SUCCESS
     */
    @ApiOperation(value = "删除用户", notes="根据url的id来指定删除对象")
    @ApiImplicitParam(name = "id",value = "用户ID",required = true,dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    public String deleteUser(@PathVariable int id){
        String returnMessage = userReponsitory.deleteUser(id);
        return returnMessage;
    }

启动应用程序，访问url：

http://localhost:8080/swagger-ui.html

返回结果

这里写图片描述

注解详解：

@Path(“users”)等同于@RequestMapping(value=”/users”)，都是定义了类的层次路径，指定了资源类提供服务的URI路径。简单的说就是定义URL
@RequestMapping(value=”/{id}”)等同于@Path(“/name/{i}”)，表示：定义了访问方法的层次路径，指定了资源类提供服务的URI路径
method=RequestMethod.DELETE等同于@DELETE，表示：方法会处理HTTP DELETE请求
@PathParam(“i”) String i ,@PathParam向@Path定义的表达式注入URI参数值
@ResponseBody表示返回json
@PathVariable 获取路径参数
@RequestParam获取request payload中的参数
@RequestBody获取request body
扩展：@Produces(MediaType.TEXT_XML)，@Produces定义了资源类方法会生成的媒体类型。
@ResponseStatus(value = HttpStatus.CREATED)，定义返回的HTTP STATUS CODE

参考扩展：
Spring Boot中使用Swagger2构建强大的RESTful API文档