swagger api 之（一）

功能

生成一个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
     */
    @ApiOperation(value = "获取用户列表",notes = "获取所有的用户的详细信息")
    @RequestMapping(value = "/users",method = RequestMethod.GET)
    public List getUsers(){
        List 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

返回结果

注解详解：

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文档