好处

  • 省得写接口文档。

代码集成

  • 引入swagger

    1.       <dependency>
    2.           <groupId>io.springfox</groupId>
    3.           <artifactId>springfox-swagger2</artifactId>
    4.           <version>2.9.2</version>
    5.       </dependency>
    6.       <dependency>
    7.           <groupId>io.springfox</groupId>
    8.           <artifactId>springfox-swagger-ui</artifactId>
    9.           <version>2.9.2</version>
    10.       </dependency>

  • 在Application.java同级创建Swagger2的配置类Swagger2

  • 此处需要注意com.didispace.web更新为你自己Controller所在路径，否则无法查询到方法。 ```java @Configuration @EnableSwagger2 public class Swagger2 {

    @Bean public Docket createRestApi() {

    1.   return new Docket(DocumentationType.SWAGGER_2)
    2.           .apiInfo(apiInfo())
    3.           .select()
    4.           .apis(RequestHandlerSelectors.basePackage("com.didispace.web"))
    5.           .paths(PathSelectors.any())
    6.           .build();

    }

    private ApiInfo apiInfo() {

    1.   return new ApiInfoBuilder()
    2.           .title("Spring Boot中使用Swagger2构建RESTful APIs")
    3.           .description("更多Spring Boot相关文章请关注：http://blog.didispace.com/")
    4.           .termsOfServiceUrl("http://blog.didispace.com/")
    5.           .contact("程序猿DD")
    6.           .version("1.0")
    7.           .build();

    }

}

  2. - 在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过`@ApiOperation`注解来给API增加说明、通过`@ApiImplicitParams`、`@ApiImplicitParam`注解来给参数增加说明。
  3. - 在Controller代码里加入注释即可（如下述的@ApiOperation）
  4. ```java
  5. @RestController
  6. @RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下，可去除
  7. public class UserController {
  9.     static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
  11.     @ApiOperation(value="获取用户列表", notes="")
  12.     @RequestMapping(value={""}, method=RequestMethod.GET)
  13.     public List<User> getUserList() {
  14.         List<User> r = new ArrayList<User>(users.values());
  15.         return r;
  16.     }
  18.     @ApiOperation(value="创建用户", notes="根据User对象创建用户")
  19.     @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  20.     @RequestMapping(value="", method=RequestMethod.POST)
  21.     public String postUser(@RequestBody User user) {
  22.         users.put(user.getId(), user);
  23.         return "success";
  24.     }
  26.     @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
  27.     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  28.     @RequestMapping(value="/{id}", method=RequestMethod.GET)
  29.     public User getUser(@PathVariable Long id) {
  30.         return users.get(id);
  31.     }
  33.     @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
  34.     @ApiImplicitParams({
  35.             @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
  36.             @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  37.     })
  38.     @RequestMapping(value="/{id}", method=RequestMethod.PUT)
  39.     public String putUser(@PathVariable Long id, @RequestBody User user) {
  40.         User u = users.get(id);
  41.         u.setName(user.getName());
  42.         u.setAge(user.getAge());
  43.         users.put(id, u);
  44.         return "success";
  45.     }
  47.     @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
  48.     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  49.     @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
  50.     public String deleteUser(@PathVariable Long id) {
  51.         users.remove(id);
  52.         return "success";
  53.     }
  55. }

UserModel

  • 上述代码需要用到的 ```java @Data @ApiModel public class User { @ApiModelProperty(value=”id-1”) private Long id;

    @ApiModelProperty(value=”username-1”) private String name;

    @ApiModelProperty(value=”age-1”) private String age;

    //getter,setter }

```

注意事项

  • 问题一：若无法显示接口，请检查RequestHandlerSelectors.basePackage是否已更新路径。
  • 问题二：如果使用了SpringSecurity，记得更新设置权限（以防路径被拦截）。

参考资料