swagger api 之（一）

骑猪看日落 2022-06-09 00:53 228阅读 0赞

*   *  功能
     *  技术与IDE
     *  代码参考github
     *  代码片段
     *  启动应用程序访问url
     *  返回结果
     *  注解详解

## 功能 ##

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

![这里写图片描述][SouthEast]

## 技术与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][http_localhost_8080_swagger-ui.html]

## 返回结果 ##

![这里写图片描述][SouthEast 1]

![这里写图片描述][SouthEast 2]

## 注解详解： ##

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

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

[SouthEast]: /images/20220609/8ce620bf0fd14bf398ed097f3997d24e.png
[Swagger-Restful-Api]: https://github.houston.entsvcs.net/private/Swagger-Restful-Api
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[SouthEast 1]: /images/20220609/fd9428cc14ef4629960171d4e9db809f.png
[SouthEast 2]: /images/20220609/7acf9353509d43708a0e60a907fa152d.png
[Spring Boot_Swagger2_RESTful API]: http://www.jianshu.com/p/8033ef83a8ed