Swagger使用导入配置

贾富荣

已于 2022-10-04 17:23:23 修改

阅读量1.8k

点赞数

分类专栏：项目搭建文章标签： java spring boot intellij-idea

于 2021-12-27 14:18:44 首次发布

本文链接：https://blog.csdn.net/xiaolajiisme/article/details/122171185

版权

项目搭建专栏收录该内容

15 篇文章 0 订阅

订阅专栏

Swagger

了解Swagger的概念及作用
了解前后端分离
在springboot中集成swagger
Restful Api 文档在线自动生成器 => API 文档与API 定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

SpringBoot集成Swagger

SpringBoot集成Swagger => springfox，两个jar包

1 SpringBoot集成Swagger

新建一个SpringBoot + Web项目

导入相关依赖

<!--swagger 相关依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

编写一个工程

配置Swagger==》config

@Configuration
@EnableOpenApi //开启swagger2
public class SwaggerConfig {

}

测试运行

地址：Swagger UI

配置Swagger

Swagger的bean实例Docket；

//配置Swagger的Docket的bean实例
    //enable(false)是否启动Swagger，如果为false，则不能在浏览器中访问
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(true)
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage：指定要扫描的包
                //any（）：扫描全部包
                //none 都不扫描
                //withClassAnnotation：扫描类上的方法
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.smile.controller"))
               // .paths(PathSelectors.ant(("/smile/**")))    //过滤扫描路径
                .build();
    }

通过不同环境开启swagger

//设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");
    //通过enviroment.acceptsProfiles判断是否处在自己设定的环境中
    boolean flag = environment.acceptsProfiles(profiles); //通过此处判断



    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(flag)
            .select()
            //RequestHandlerSelectors,配置要扫描接口的方式
            //basePackage：指定要扫描的包
            //any（）：扫描全部包
            //none 都不扫描
            //withClassAnnotation：扫描类上的方法
            //withMethodAnnotation:扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.smile.controller"))
           // .paths(PathSelectors.ant(("/smile/**")))    //过滤扫描路径
            .build();
}

2 分组及接口注释小结

.groupName("贾富荣")

如何配置多个分组：多个Docket实例即可

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

给生成的文档加注释：

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

部分：

package com.smile.controller;

import com.smile.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
//ApiOperation接口
@ApiOperation("Hello控制类接口注释")
@RestController
public class HelloController {

    //ApiOperation接口，不是放在类上的，是方法
    @ApiOperation("hello控制类")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user(){
        return new User("贾富荣","111111");
    }

    @ApiOperation("Post测试")
    @PostMapping("/postt")
    public User postt(@ApiParam("用户名：")User user){
        return user;
    }
}

项目使用搭建代码：

Swagger2

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTFUL风格的Web服务

生成在线接口文档
方便接口测试

1.导入swaager依赖

<!--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>

2.创建配置类

package com.smile.servicebase;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author jia
 * @date 2022/8/14
 * @description swagger配置文件
 */

@Configuration
@EnableSwagger2 //swagger注解
public class SwaggerConfig {
    /**
     * swagger插件
     * @return
     */
    @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();
    }
    //文档信息设置
    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("网站-课程中心API文档")
                .description("本文档描述了课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("Helen", "http://atguigu.com",
                        "2413249299@qq.com"))
                .build();
    }
}

3.在主启动类中添加注解，设置包扫描规则

 *   注意在common中，如果在其他地方使用会涉及没启用可能，需要使用@ComponentScan(basePackages = {"com.smile"})
 *
 */

@SpringBootApplication
@ComponentScan(basePackages = {"com.smile"})  //会扫描所有这个路径下的类，包含父类中的这个路径
public class EduApplication {
    public static void main(String[] args) {
        SpringApplication.run(EduApplication.class,args);
    }
}

4.访问swagger

http://localhost:8001/swagger-ui.html

5.Controller层代码

@Api(description = "讲师管理")  //controller提示信息
@RestController
@RequestMapping("/eduservice/edu-teacher")
public class EduTeacherController {

    @Autowired
    private EduTeacherService eduTeacherService;

    //查询讲师表中的所有数据 restful风格
    @ApiOperation(value = "所有讲师列表") //单个接口提示信息
    @GetMapping("findAll")
    public List<EduTeacher> findAllTeacher(){
        //调用service方法，实现查询所有的操作
        List<EduTeacher> list = eduTeacherService.list(null);
        return list;
    }

    //逻辑删除讲师的方法
    @ApiOperation(value = "逻辑删除讲师")
    @DeleteMapping("{id}")  //id需要通过路径进行传递 so 下面的参数值   delete不能使用浏览器直接进行测试，swagger测试
    //参数值信息@ApiParam(value = "讲师ID",name = "id",required = true)
    public boolean removeTeacher(@ApiParam(value = "讲师ID",name = "id",required = true)@PathVariable String id){
        boolean flag = eduTeacherService.removeById(id);
        return flag;
    }

}