SpringBoot--Swagger

2023-10-22 09:37:04

目录

1、Swagger简介

  1. Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
  2. RestFul API 文档在线自动生成工具 API 文档与 API 定义同步更新
  3. 直接运行，可以在线测试 API 接口
  4. 支持多种语言

2、SpringBoot集成Swagger

  • 导入依赖
<!-- springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
  • 编写配置类 SwaggerConfig
package com.example.demo.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
  • 测试运行

访问地址：http://localhost:8080/swagger-ui.html

SpringBoot--Swagger

3、配置Swagger

Swagger 的实例 docket

3.1、配置作者信息与项目简介

Docket .apiInfo();

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    //配置Swagger Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
            //配置Swagger信息
            .apiInfo(toApiInfo());
    }
    
    //配置Swagger信息 = ApiInfo
    public ApiInfo toApiInfo(){
        //作者信息
        Contact contact = new Contact("秦疆", "www.baidu.com", "2625445438@qq.com");
        return new ApiInfo(
            "狂神老师的SwaggerAPI文档",
            "即使再小的帆也能远航",
            "v1.0",
            "www.baidu.com",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
    }
    
}

SpringBoot--Swagger

3.2、配置扫描指定接口

Docket.select();

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {


    //配置Swagger Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
            //配置Swagger信息
            .apiInfo(toApiInfo())
            //指定扫描的接口
            .select()
            //扫描路径
            //basePackage:指定要扫描的包
            //any():扫描全部
            //none():不扫描
            //withClassAnntation() 扫描类上的注解,参数是一个注解的反射对象
            //withMethodAnntation() 扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            //配置过滤路径
            .paths(PathSelectors.any())
            .build();
    }

    //配置Swagger信息 = ApiInfo
    public ApiInfo toApiInfo(){
        //作者信息
        Contact contact = new Contact("秦疆", "www.baidu.com", "2625445438@qq.com");
        return new ApiInfo(
            "狂神老师的SwaggerAPI文档",
            "即使再小的帆也能远航",
            "v1.0",
            "www.baidu.com",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());

    }

}

SpringBoot--Swagger

3.3、配置Swagger是否自动启动

.enable(false) 默认为 true，如果为 false 则浏览器不能访问
SpringBoot--Swagger

SpringBoot--Swagger

3.4、配置文档分组

.groupName("Tony") 配置文档分组

SpringBoot--Swagger

SpringBoot--Swagger

配置多个分组：同时配置多个 Docket 就会有多个分组

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(toApiInfo())
        .groupName("刘翔");//配置文档分组
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(toApiInfo())
        .groupName("姚明");//配置文档分组
}

SpringBoot--Swagger

3.5、实体类配置

  • 编写 pojo 实体类
package com.example.demo.pojo;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

//@Api("用户实体类")
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("id")
    int id;
    @ApiModelProperty("姓名")
    String name;
    @ApiModelProperty("年龄")
    int age;
    @ApiModelProperty("性别")
    String sex;

    public User() {
    }

    public User(int id, String name, int age, String sex) {
        this.id = id;
        this.name = name;
        this.age = age;
        this.sex = sex;
    }

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }
}
  • 编写 HelloController
package com.example.demo.controller;

import com.example.demo.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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    //只要我们的接口中返回值中存在实体类，它就会被扫描到Swagger中
    @RequestMapping("/user")
    public User getUser(){
        return new User();
    }

    //ApiOperation,不是放在类上的，是方法
    @ApiOperation("Hello控制类")
    @GetMapping(value = "/hello")
    public String Hello(@ApiParam("用户名") String username){
        return "hello"+username;
    }
}

SpringBoot--Swagger

4、注解整理与小结

  • 注解整理

Pojo vo类使用有：

  1. @Api(注释) 指定 vo 类的说明
  2. @ApiModel("用户实体类") 指定 vo 类的说明
  3. @ApiModelProperty("id") 指定 vo 属性说明

接口类使用有:

  1. @ApiOperation("返回User类") 方法上定义 用于说明接口是干嘛的
  2. @ApiParam("传入name参数") 方法的入参上定义 用于传入参数说明
  • 小结
  1. 我们可以通过 Swagger 给一些比较难理解的属性或者接口，增加注释信息
  2. 接口文档实时更新、
  3. 可以在线测试

Swagger 是一个优秀的工具，几乎所有大公司都有使用它。

注意点：在正式发布的时候，出于安全考虑以及节省运行的内存，关闭 Swagger! ! !

5、题目

我只希望我的 Swagger 在生产环境中使用，在发布的时候不使用，如何操作？

解决流程：1. 判断是不是生产环境（flag = false）2. 注入 enable（flag）

  1. 配置 application.properties、application-dev.properties 和 application-pro.properties 三套环境
  2. 设置端口分别为8080、8081和8082，并激活 application-dev.properties 环境

SpringBoot--Swagger

  1. 编写 SwaggerConfig
package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    //配置Swagger Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

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


        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(toApiInfo())
            .enable(true)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .build();
    }

    //配置Swagger信息 = ApiInfo
    public ApiInfo toApiInfo(){
        //作者信息
        Contact contact = new Contact("秦疆", "www.baidu.com", "2625445438@qq.com");
        return new ApiInfo(
            "狂神老师的SwaggerAPI文档",
            "即使再小的帆也能远航",
            "v1.0",
            "www.baidu.com",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());

    }

}
  1. 测试

可以通过8081端口使用当前的 application-dev.properties 环境，其它环境则不能使用。

SpringBoot--Swagger

SpringBoot--Swagger

SpringBoot--Swagger

上一篇：Swagger


下一篇：Django 相关操作