Spring Boot 中 配置 Swagger

本文不是对Swagger的学习,只是记录如何配置Swagger
简单学习Swagger可以看这篇博文:swagger使用指南

Swagger Api注解速览


@Api:               用于类,标识这个类是swagger的资源
@ApiIgnore:         用于类,忽略该 Controller,指不对当前类做扫描
@ApiOperation:      用于方法,描述 Controller类中的 method接口
@ApiParam:          用于参数,单个参数描述,与 @ApiImplicitParam不同的是,他是写在参数左侧的。如( @ApiParam(name="username",value="用户名")String username)
@ApiModel:          用于类,表示对类进行说明,用于参数用实体类接收
@ApiModelProperty:       用于方法,字段,表示对model属性的说明或者数据操作更改
@ApiImplicitParam:  用于方法,表示单独的请求参数
@ApiImplicitParams: 用于方法,包含多个 @ApiImplicitParam
@ApiResponse:       用于方法,描述单个出参信息
@ApiResponses:      用于方法,包含多个@ApiResponse
@ApiError:          用于方法,接口错误所返回的信息

挂张图:

开始配置

1. 导入依赖

配置基于Spring Boot 2.2.1


    <properties>
      <swagger.version>2.9.2</swagger.version>
    </properties>

      ...

    <!-- swagger2  来自RuoYi -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>${swagger.version}</version>
      <exclusions>
        <exclusion>
          <groupId>io.swagger</groupId>
          <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
          <groupId>io.swagger</groupId>
          <artifactId>swagger-models</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

    <!--防止进入swagger页面报类型转换错误,排除2.9.2中的引用,手动增加1.5.21版本-->
    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-annotations</artifactId>
      <version>1.5.21</version>
    </dependency>

    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-models</artifactId>
      <version>1.5.21</version>
    </dependency>

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

2. 写配置文件

application.properties

  # application.properties中控制是否开启swagger
  swagger.enabled=true

SwaggerConfig.java

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    /** 是否开启swagger */
    @Value("${swagger.enabled}")
    private boolean enabled;

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用Swagger
                .enable(enabled)
                // 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api,用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题:XX管理系统_接口文档")
                // 描述
                .description("描述:用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                // 作者信息
                .contact(new Contact("xxx项目", null, null))
                // 版本
                .version("版本号:" + "v1.1.0")
                .build();
    }

}

3. 编写测试类,并添加相关API注解

Student.java


/**
 * @author liuyiyuan
 */

@ApiModel(description="学生数据类型")
public class Student {
    @ApiModelProperty(value = "学生姓名", name="name",
            dataType="String",
            required=true,
            position=3,  //排序,越小越靠前
            example="tom")
    private String name;
    @ApiModelProperty(value = "学生班级名", name="className",
            required=true,
            dataType="String",
            position=5,
            example="tom")
    private String className;
    @ApiModelProperty(value = "学生年龄", name="age",
            required=true,
            dataType="Integer",
            position=2,
            example="15")
    private Integer age;

    public Student(String name, String className, Integer age) {
        this.name = name;
        this.className = className;
        this.age = age;
    }
      //getter、setter
}

Controller

/**
 * @author liuyiyuan
 */

@Api(value = "学生管理模块API", tags = "学生管理")
//@ApiIgnore //忽略本类中的api
@RestController
@RequestMapping("/stu")
public class StudentController {

    @ApiResponse(
            code = 200,
            message = "成功",
            response = ArrayList.class
    )
    @ApiOperation(value = "获取列表",
            tags = {"tag2..", "分为多个标签"},
            httpMethod = "GET")
    @GetMapping("/stus")
    public List<Student> listStudent() {
        List<Student> ss = new ArrayList<>();
        ss.add(new Student("aaa", "1班", 13));
        ss.add(new Student("bbb", "2班", 15));
        ss.add(new Student("ccc", "3班", 11));
        ss.add(new Student("ddd", "4班", 16));
        return ss;
    }


    @ApiResponse(
            code = 200,
            message = "成功",
            response = Student.class
    )
    @ApiOperation(value = "获取一个对象",
            tags = {"tag1..", "分为多个标签"},
            nickname = "昵称",
            httpMethod = "GET")
    @GetMapping("/stu")
    public Student getStudent(@ApiParam(name = "idx", value = "要获取学生数据的索引值", defaultValue = "1") @RequestParam("idx") Integer index) {
        List<Student> ss = new ArrayList<>();
        ss.add(new Student("aaa", "1班", 13));
        ss.add(new Student("bbb", "2班", 15));
        ss.add(new Student("ccc", "3班", 11));
        ss.add(new Student("ddd", "4班", 16));


        return ss.get(index);
    }


    @ApiImplicitParam(
            name = "student",
            value = "要插入的新数据",
            required = true,
            dataType = "Student",
            paramType = "body"
    )
    @ApiOperation(value = "插入新值")
    @PostMapping("/stus")
    public Student post(@RequestBody Student student) {
        System.out.println("插入新值...===> " + student);
        return student;
    }


    @ApiOperation(value = "修改")
    @ApiImplicitParam(
            name = "student",
            value = "要修改的新学生数据",
            required = true,
            paramType = "body",
            dataType = "Student"
    )
    @PutMapping("/stus")
    public Student put(@RequestBody Student student) {
        System.out.println("修改新值...===> " + student);
        return student;
    }


    @ApiOperation(value = "删除",
            httpMethod = "DELETE")
    @DeleteMapping("/stus/{idx}")
    @ApiImplicitParam(name = "idx", value = "删除对象的索引值", paramType = "path")
    public Student del(@PathVariable("idx") Integer index) {
        List<Student> ss = new ArrayList<>();
        ss.add(new Student("aaa", "1班", 13));
        ss.add(new Student("bbb", "2班", 15));
        ss.add(new Student("ccc", "3班", 11));
        ss.add(new Student("ddd", "4班", 16));
        System.out.println("删除值==> " + ss.get(index));

        return ss.get(index);
    }
}

4. 访问

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

posted @ 2020-08-22 16:53  originyuan  阅读(867)  评论(0编辑  收藏  举报