配置Swagger2生成API接口文档

配置Swagger2生成API接口文档

Swagger简介

前后端分离开发模式中， api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

前后端分离开发模式中， api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

1. 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3. 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4. 可测性 (直接在接口文档上进行测试，以方便理解业务)

在模块service-base中，改pom.xml文件

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <scope>provided</scope>
        </dependency>
        <!--mybatis-plus-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <scope>provided</scope>
        </dependency>
        <!--lombok用来简化实体类：需要安装lombok插件-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <scope>provided</scope>
        </dependency>
        <!-- redis -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>
        <!-- spring2.X集成redis所需common-pool2
        <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-pool2</artifactId>
    <version>2.6.0</version>
        </dependency>-->
    </dependencies>

在模块service-base中，创建swagger的配置类

@Configuration
@EnableSwagger2    // Swagger注解
public class SwaggerConfig {

    // 配置swagger的插件
    @Bean
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                // 下面的是如果接口路径中如果包含admin，error就不进行显示
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();
    }

    /**
     * 表示设置在线文档的一些信息
     * @return
     */
    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("网站-课程中心API文档")
                .description("本文档描述了课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("java", "http://atguigu.com",
                        "55317332@qq.com"))
                .build();
    }

}

然后在需要用到Swagger2的模块中导入service_base的依赖

引入service_base的坐标

        <dependency>
            <groupId>com.atguigu</groupId>
            <artifactId>service_base</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>

注意

如果被引入模块的包的命名和引入的模块的包的命名不一致要将Swagger的配置类扫描到ioc容器，否则无法注入。

@SpringBootApplication
// 因为SwaggerConfig不在com.atguigu.eduservice下面，所以得把包扫描的范围给改一下
// 要么就将两个某块的命名 设置相同即可
@ComponentScan("com.atguigu")
public class EduTeacherApplication {
    public static void main(String[] args) {
        SpringApplication.run(EduTeacherApplication.class, args);
    }
}

定义接口说明和参数说明

• 定义在类上： @Api
• 定义在方法上： @ApiOperation
• 定义在参数上： @ApiParam

/**
 * <p>
 * 讲师 前端控制器
 * </p>
 *
 * @author pzx
 * @since 2022-01-23
 */
@Api(description = "讲师管理")
@RestController
@RequestMapping("/eduservice/edu-teacher")
public class EduTeacherController {
    @Autowired
    private EduTeacherService eduTeacherService;


    // 所有讲师列表
    // rest风格
    @GetMapping("/getAll")
    @ApiOperation(value = "所有讲师列表")
    public List<EduTeacher> getAll() {
        return eduTeacherService.list(null);
    }


    // 逻辑删除讲师
    @DeleteMapping("/{id}")
    @ApiOperation(value = "根据ID删除讲师")
    public boolean removeTeacher(@ApiParam(name = "id", value = "讲师ID", required = true)
                                 @PathVariable("id") String id) {
        boolean result = eduTeacherService.removeById(id);
        return result;
    }

}
    

测试Swagger

1. 在浏览器中输入地址http://localhost:8001/swagger-ui.html

2. 测试接口