spring-boot-route（五）整合 Swagger 生成接口文档

Java旅途

关注

发布于: 2020 年 10 月 06 日

目前，大多数公司都采用了前后端分离的开发模式，为了解决前后端人员的沟通问题，后端人员在开发接口的时候会选择使用 swagger2 来生成对应的接口文档，swagger2 提供了强大的页面调试功能，这样可以有效解决前后端人员沟通难的问题。

下面我们使用 SpringBoot 结合 swagger2 生成 Restful API 文档。

一搭建项目，引入依赖

新建一个spring-boot-swaager的项目，引入 swaager2 的依赖，由于 swagger2 的 ui 不是很美观，这里将使用开源的swagger-bootstrap-ui做为 ui。

引入依赖

<!-- swaager2依赖 -->    <dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.9.2</version></dependency><!-- swaager2ui --><dependency>    <groupId>com.github.xiaoymin</groupId>    <artifactId>swagger-bootstrap-ui</artifactId>    <version>1.9.6</version></dependency>

复制代码

项目中配置 swagger 相关信息

@Configuration@EnableSwagger2public class configuration {
    @Bean    public Docket createRestApi(){        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.javatrip.swagger.controller"))                .paths(PathSelectors.any())                .build();    }
    private ApiInfo apiInfo(){        return new ApiInfoBuilder()                // 标题                .title("某某项目接口文档")                // 描述                .description("swagger2接口文档使用演示")                // 版本                .version("1.0")                // 许可证                .license("MIT")                // 许可证地址                .licenseUrl("www.xx.com")                // 服务端地址                .termsOfServiceUrl("https://www.cnblogs.com/zhixie/")                // 联系信息                .contact(new Contact("java旅途","https://www.cnblogs.com/zhixie/","binzh303@163.com"))                .build();    }}

复制代码

访问路径，查看生成效果

文章中使用的这个 ui，接口文档地址为ip:port/doc.html，生成的文档信息如下：

二编写 Restful 接口

新建实体类

@ApiModel("用户实体类")@Data@NoArgsConstructor@AllArgsConstructorpublic class Person {    @ApiModelProperty("姓名")    private String name;    @ApiModelProperty(value = "年龄")    private int age;}

复制代码

新建 Restful 接口

@Api(tags = "用户接口")
@RestController
@RequestMapping("person")
public class PersonController {

    @ApiOperation(value = "获取用户列表",notes = "根据name获取用户列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true),
            @ApiImplicitParam(name = "age",value = "年龄",dataType = "int",required = true)
    })
    @GetMapping("/{name}")
    public Person getPerson(@PathVariable("name") String name,@RequestParam int age){
        return new Person(name,age);
    }

    @ApiOperation(value = "新增用户",notes = "根据用户实体类新增用户")
    @ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
    @PostMapping("add")
    public int addPerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "更新用户信息",notes = "根据用户实体更新用户信息")
    @ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
    @PutMapping("update")
    public int updatePerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "删除用户信息",notes = "根据用户名删除用户信息")
    @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true)
    @DeleteMapping("/{name}")
    public int deletePerson(@PathVariable(name = "name") String name){
        if(StringUtils.isEmpty(name)){
            return -1;
        }
        return 1;
    }
}