接口文档转java 接口文档生成工具 swagger

转载

mob64ca140530fb 2023-11-11 11:45:30

文章标签 接口文档转java spring boot swagger2 api 接口文档 文章分类 Java 后端开发

文章目录

Swagger 简介
1、创建项目
2、导入 Swagger 依赖
3、配置 Swagger
4、编写接口，添加注释
5、查看接口文档
6、在线测试接口

Swagger 简介

前后端分离的架构中，往往需要构建接口文档。而接口文档中需要定义各种各样的参数，单独写起来比较繁琐，尤其是当接口十分多时，效率十分低下。同时，传统的接口维护十分不方便，一旦接口发生变换，文档就必须跟着修改。除此之外，接口测试往往需要通过第三方工具（如 Postman）进行。Swagger 的诞生就是为了解决上述种种问题。

Swagger 作为一款优秀的 Api 接口文档生成工具，主要提供如下两个功能：

接口文档实时更新：只需在项目通过配置 + 注解即可快速生产接口文档，并且能够实时更新，可维护性强
可以在线测试接口：提供在线测试功能，无需使用第三方软件进行接口测试

1、创建项目

创建一个 Spring Boot 项目，如果官网进不去，可以采用如下地址：https://start.aliyun.com/ 创建

接口文档转java 接口文档生成工具 swagger_spring boot

下一步

接口文档转java 接口文档生成工具 swagger_接口文档_02

添加 web 依赖

接口文档转java 接口文档生成工具 swagger_swagger2_03

Finish 完成

接口文档转java 接口文档生成工具 swagger_接口文档转java_04

2、导入 Swagger 依赖

在 pom.xml 中，添加如下依赖：

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

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

3、配置 Swagger

创建一个名为 SwaggerConfig 的类，并在类名上方添加 @Configuration 以及 @EnableSwagger2 注解

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment) {
//        Profiles profiles = Profiles.of("dev", "test");
//        boolean b = environment.acceptsProfiles(profiles);
//        可在下方添加 .enbale(b)，这样就可以实现根据配置环境决定是否开启 Swagger 访问
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.study.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .description("小白接口测试文档")
                        .contact(new Contact("努力学习","authorURL","authorEmail"))
                        .version("v1.0")
                        .title("API 测试文档")
                        .license("Apache2.0")
                        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                        .build());
    }

}

apis 中定义的 backPackage 为需要扫描的包，指定为 controller 所在的包即可
apiInfo 中的各个参数对应文档的相关描述信息、如标题、作者、版本、描述等

注释部分解释：

通过 Environment 参数可以获取当前的环境，如果配置环境为 Profiles.of("dev", "test") 中参数定义的，则传入 enable 的值为 true，否则为 false，只有当 enable 的值为 true 时才能访问 Swagger 文档，当我们正式上线项目时需要关闭接口文档，即上线的环境对应的配置文件名不要出现在 Profiles.of() 中的参数中，这样得到的 boolean 变量 b 的值就 false，Swager 文档将关闭

如果要创建组，可添加 groupName 参数，创建多个组则定义多个 Docket方法，在其中指定 groupName 即可。

先运行 Spring Boot 项目查看一下效果，在浏览器地址栏中输入 localhost:8080/swagger-ui.html

接口文档转java 接口文档生成工具 swagger_api_05

以后我们只要输入上面那个地址即可访问接口文档。

4、编写接口，添加注释

开启了 Swagger 之后，我们就可以在 Controller 中写接口了。

@RestController
@RequestMapping("/students")
@Api(tags = "学生数据接口")
public class StudentController {

    @GetMapping("/{id}")
    @ApiOperation(value = "查询学生", notes = "根据学号查询学生")
    @ApiImplicitParam(paramType = "path",name = "id",value = "学生学号",required = true)
    public RespBean getStudentById(@PathVariable("id") int id) {
        return new RespBean("success","查询学号为"+id+"的学生成功！");
    }

    @DeleteMapping("/{id}")
    @ApiResponses({
            @ApiResponse(code = 200, message = "删除成功！"),
            @ApiResponse(code = 500, message = "删除失败！")
    })
    @ApiOperation(value = "删除学生", notes = "通过学号删除学生")
    public RespBean deleteStudentById(@PathVariable("id") int id) {
        return new RespBean("success","删除学号为"+id+"的学生成功！");
    }

    @ApiOperation(value = "增加学生", notes = "传入姓名与密码，以添加学生")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "name", value = "学生姓名", required = true, defaultValue = "aaa"),
            @ApiImplicitParam(paramType = "query", name = "pwd", value = "学生密码", required = true, defaultValue = "123")
    })
    @PostMapping("/")
    public RespBean addStudent(@RequestParam("name") String name, @RequestParam("pwd") String pwd) {
        return new RespBean("success","增加了name为"+name+"的学生！");
    }

    @PutMapping("/")
    @ApiOperation(value = "更新学生", notes = "传入姓名与密码，以更新学生")
    public RespBean updateStudent(@RequestBody Student student) {
        return new RespBean("success","更新后的学生信息为："+student.toString());
    }

}