Swagger的简单使用

简介

在如今前后端分离的趋势下，接口成为了前后端进行交互的方式，因而需要编写开发文档来进行交流
而且，对于后端人员的开发测试也是一件比较痛苦的事
这时就可使用到swagger来辅助开发

依赖

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

配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("在线教育API文档")
                .description("本文档描述了在线教育微服务接口定义")
                .version("1.0")
                .contact(new Contact("mfqh", "http://mfqh.com", "[e-mail]"))
                .build();
    }

}

使用实例

@Api(description = "管理页面讲师接口")
@RestController
@RequestMapping("/servicedu/teacher")
@CrossOrigin
public class EduTeacherController {

    @Autowired
    private EduTeacherService eduTeacherService;


    @ApiOperation(value = "查询所有讲师")
    @GetMapping("findAll")
    public ResultJson findAll(){
        return ResultJson.ok().data("items",eduTeacherService.list(null));
    }

    @ApiOperation(value = "根据id删除讲师")
    @DeleteMapping("delete/{id}")
    public ResultJson delete(@PathVariable("id") String id){
        Boolean flag = eduTeacherService.removeById(id);
        if(flag == false){
            return ResultJson.error();
        }
        return ResultJson.ok();
    }

    @ApiOperation(value="根据条件进行分页查询")
    @PostMapping("pageList/{page}/{number}")
    public ResultJson pageList(@PathVariable("page") Long page,
                               @PathVariable("number") long number,
                               @RequestBody(required = false) TeacherCondition teacher){
        Page<EduTeacher> pageTeacher = new Page<>(page, number);

        eduTeacherService.pageQueryCondition(pageTeacher,teacher);

        return ResultJson.ok().data("total",pageTeacher.getTotal()).data("items",pageTeacher.getRecords());
    }

    @ApiOperation(value = "添加新的讲师")
    @PostMapping("addTeacher")
    public ResultJson addTeacher(@RequestBody EduTeacher teacher){
        if(eduTeacherService.save(teacher)){
            return ResultJson.ok();
        }
        return ResultJson.error();
    }

    @ApiOperation(value="根据id查询讲师")
    @GetMapping("findOne/{id}")
    public ResultJson findOne(@PathVariable(value = "id") String id){
        return ResultJson.ok().data("item",eduTeacherService.getById(id));
    }

    @ApiOperation(value = "根据id修改讲师信息")
    @PostMapping("modOne/{id}")
    public ResultJson modOne(@PathVariable(value = "id") String id,
                             @RequestBody EduTeacher eduTeacher){
        eduTeacher.setId(id);
        if(eduTeacherService.updateById(eduTeacher)){
            return ResultJson.ok();
        }
        return ResultJson.error();
    }

}