Swagger

Annotation

Refer to swagger2 注解说明

• 请求类上:

  • @Api(tags="说明该类的作用")

• 请求方法上

  • @ApiOperation(value="",notes="") 说明方法的用途、作用
  • @ApiImplicitParams({@ApiImplicitParam(xxxx),...})，@ApiImplicitParam 参数说明
    • name：参数名
    • value：参数的汉字说明、解释
    • required：参数是否必须传
    • paramType：参数放在哪个地方
      • header : 请求参数 @RequestHeader获取
      • query : 请求参数 @RequestParam 获取
      • path: 请求参数@PathVariable获取
      • body（不常用）
      • form（不常用）
    • dataType：参数类型，默认String
    • defaultValue：参数的默认值
  • @ApiResponses({@ApiResponse(xxx),...}) 表示一组响应(一般用于表达错误的响应信息)
    • code：数字，例如400
    • message：信息，例如"请求参数没填好"
    • response：抛出异常的类

• 请求响应entity上(若无特殊说明，不加注解也可，会使用默认的，即直接使用类名&字段名&类型):

  • @ApiModel（一般用在post/put创建或修改时，使用@RequestBody的场景，请求参数无法使用@ApiImplicitParam注解进行描述）

      的时候）
    

  • @ApiModelProperty：用在entity的属性上

Sample:

@ApiOperation("删除某评论")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "id", dataType = "Integer", paramType = "path"),
        @ApiImplicitParam(name = "type", value = "type", dataType = "String", paramType = "path",
                allowableValues="home,school")
})
@ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@PutMapping("/comments/{id}/{type}")
public Object updateComment(@PathVariable("id") Integer id,
        @PathVariable("type")String type,
        @RequestBody Comment comment){
   // ...
}

Sample

1. dependencies

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
   

2. configuration

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
   
        // @Value("${swagger.enable:false}")
        // private boolean enable=false;
   
        @Bean
        public Docket docket(Environment env) {
            Profiles profiles = Profiles.of("dev");
            boolean flag = env.acceptsProfiles(profiles);
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(flag) // .enable(enable)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.cj.mybatis.controller"))
                    //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                    //.paths(PathSelectors.any())
                    .build();
        }
   
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Swagger Demo")
                    .description("This for swagger demo")
                    //.termsOfServiceUrl("http://blog.csdn.net/saytime")
                    .version("1.0")
                    .build();
        }
    }
   

3. Controller

    @Api(tags="Employee Part")
    @RestController
    public class EmployeeController {
   
        @Autowired
        private EmployeeService employeeService;
   
        // ============================ CRUD ===========================
   
        @ApiOperation(value="List Emlpoyees")
        @ApiImplicitParams({
                @ApiImplicitParam(name="page",value="页码",dataType="Integer",paramType="query",required=false),
                @ApiImplicitParam(name="size",value="每页数量",dataType="Integer",paramType="query",required=false)
        })
        @GetMapping("/employees")
        public Object listEmployees(@RequestParam(name="page",required=false) Integer page
                ,@RequestParam(name="size",required=false) Integer size) {
            if(page!=null && size!=null) {
                return ResponseUtil.ok(employeeService.listByPage(page, size));
            }else {
                // return new ResponseEntity<>(employeeService.listAll(),HttpStatus.OK);
                return ResponseUtil.ok(employeeService.listAll());
            }
        }
   
        @ApiOperation("Get Employee By Id")
        @ApiImplicitParam(name="id",value="Employee唯一标识",dataType="Integer",paramType="path",required=true)
        @GetMapping("/employees/{id}")
        public Object getEmployee(@PathVariable Integer id) {
            return ResponseUtil.ok(employeeService.getEmployee(id));
        }
   
        @ApiOperation("Update Employee By Id")
        @ApiImplicitParam(name="id",value="Employee唯一标识",dataType="Integer",paramType="path",required=true)
        @PutMapping("/employees/{id}")
        public Object updateEmployee(@PathVariable("id") Integer id,@RequestBody Employee emp) {
            emp.setId(id);
            Integer result=this.employeeService.updateEmployee(emp);
            return ResponseUtil.result(result==1, result);
        }
   
        @ApiOperation("Add Employee")
        @PostMapping("/employees")
        public Object insertEmployee(@RequestBody Employee emp) {
            emp.setId(null);
            Integer result = this.employeeService.insertEmployee(emp);
            return ResponseUtil.result(result!=null, result);
        }
   
        @ApiOperation("Delete Employee By Id")
        @ApiImplicitParam(name="id",value="Employee唯一标识",dataType="Integer",paramType="path",required=true)
        @DeleteMapping("/employees/{id}")
        public Object deleteEmployee(@PathVariable Integer id) {
            Integer result = this.employeeService.deleteEmployee(id);
            return ResponseUtil.result(result==1, result);
        }
    }
   

4. entity

    @ApiModel("Employee Model")
    @Data
    public class Employee {
   
        @ApiModelProperty("唯一标识")
        private Integer id;
   
        @ApiModelProperty("名称")
        private String name;
   
        @ApiModelProperty("备注")
        private String remark;
   
        @ApiModelProperty(name="部门Id",notes="Department table primary key")
        private Integer departmentId;
    }
   

5. run then visit: http://localhost:8080/demo/swagger-ui.html