Swagger

强烈建议使用Swagger，做到代码在文档就在。很多项目发现代码有，但是没有接口文档，所以很难维护。

依赖

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
</dependency>
<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.ui.version}</version>
</dependency>

Swagger2的Bean配置

@Configuration
@EnableSwagger2 // 使能Swagger2
public class Swagger2Config {

    private final Logger logger = LoggerFactory.getLogger(Swagger2Config.class);

    @Value("${spring.profiles.active}")
    private String springProfilesActive;

    @Bean
    public Docket createRestApi() {

        // 根据环境确定是否启动swagger，只有开发环境才显示，否则公网也看到文档不安全
        boolean enable = EnvConstants.DEV.equals(springProfilesActive);
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.changhong.touchc.fastdfs.controller.manage"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxxxxx")
                .description("yyyyyy")
                .version("1.0")
                .build();
    }

}

注解

@Api(tags = {"个人文件管理接口"})
@Controller
@RequestMapping("/manage/file")
public class ManageFileController extends BaseController{

    @ApiOperation(value = "分页显示文件")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum", value = "每页条数", dataTypeClass = Integer.class, paramType = "query",defaultValue = "10")
            })
    @ApiResponses({@ApiResponse(code = 200,message = "成功", response = FilePageDTO.class)})
    @GetMapping(value = "/pageInfoFileRecord")
    ResponseEntity getFileRecord(@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
                                 @ApiParam(value = "需要删除文件的fileGlobalId数组") @RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum) {
 
    return new ResponseEntity(filePageDTO, HttpStatus.OK);

    }
}

@Data
@ApiModel(description = "文件分页显示列表")
public class FilePageDTO {

    @ApiModelProperty(value = "文件类型数据字典", example = "1")
    private Map<String, String> fileSourceMap;
    @ApiModelProperty(value = "文件分页参数")
    private PageInfo<FileRecordDO> pageInfo;

}

@RequestMapping(value = "/updateFileName", method = RequestMethod.POST)
@ApiResponses({@ApiResponse(code = 204, message = "更新成功")})
ResponseEntity updateFileName(@RequestBody UpdateFileNameDTO updateFileNameDTO){
     
      return new ResponseEntity(HttpStatus.NO_CONTENT);

}

@Data
@ApiModel(value = "更新文件名称传输对象")
public class UpdateFileNameDTO {

    @ApiModelProperty(value = "新文件名称", example = "新文档.txt")
    private String newFileName;
}

@Api(tags = {"个人文件管理接口"})
@ApiOperation(value = "分页显示文件")

@ApiImplicitParams
@ApiImplicitParam

@ApiParam  注意只有value参数起效，example参数不起效，可以注解到@RequestParam,@PathVariable,@RequestBody

 

@ApiModel(description = "文件分页显示列表")
@ApiModelProperty(value = "文件类型数据字典", example = "1")
swagger对实体传输对象显示的兼容性最佳

请求参数DTO

响应参数DTO