springboot配置Swagger3.0

Posted 2023-05-28 阳家坡对面的荫凉

springboot配置Swagger3.0

1、pom加入依赖

我们创建一个SpringBoot项目，引入 swagger3 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2、启动类上加入注解

在启动类上加入两个注解，即可开启 swagger3

@SpringBootApplication
@EnableSwagger2
@EnableOpenApi
public class NacosApplication 

    public static void main(String[] args) 
        SpringApplication.run(NacosApplication.class, args);
        System.out.println("我是 nacos 微服务");
    

对于swagger，简单的配置就可以看到页面了，我们我输入 localhost:8080/swagger-ui/index.html

3、创建Swagger配置类

对于swagger，我们可以对 index.html 页面做一些配置，比如邮箱、姓名、git地址等。

@Configuration
public class SwaggerConfiguration 

    @Bean
    Docket docket() 
        return new Docket(DocumentationType.OAS_30)
                // 配置网站基本信息
                .apiInfo(new ApiInfoBuilder()
                        .title("nacos微服务接口文档")
                        .version("v1.0")
                        .description("在线nacos微服务接口文档")
                        .contact(new Contact("choleen", "https://choleen95.github.io/",
                                ""))
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.nacos.controller"))
                .build();

    

目前，对于请求，我们配置了对于controller包下的所有类的接口，都展示在上面。

4、创建接口-三种

目前创建三种接口，一种是form表单传值，一种是路径传参，一种是实体传参

@Api("查询演出接口")
@RequestMapping("/hello/")
@RestController
public class HelloController 

    private static final Logger logger = LoggerFactory.getLogger(HelloController.class);
    @Resource(name = "activityMapper")
    ActivityMapper activityMapper;

    @ApiOperation("根据场地城市及Id查询演出表")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "venueCity", value = "场地城市"),
            @ApiImplicitParam(name = "id", value = "id")
    )
    @GetMapping("activity")
    public ResponseHelper sayHello(String venueCity, @RequestParam(required = true) String id) 
        List<Activity> list = activityMapper.queryEntityList(venueCity, id);
        return ResponseHelper.build(200, list);
    

    @ApiOperation("根据id查询演出")
    @ApiImplicitParam(name = "id", value = "id")
    @GetMapping("id")
    public ResponseHelper queryInfo(@PathVariable(value = "id")Long id) 
        Activity activity = activityMapper.selectById(id);
        return ResponseHelper.build(200, activity);
    

    @ApiOperation("分页查询演出")
    @ApiImplicitParam(name = "activity", value = "演出实体")
    @GetMapping("queryByPage")
    public ResponseHelper queryByActivity(@RequestBody Activity activity) 
        QueryWrapper<Activity> wrapper = new QueryWrapper<>();
        wrapper.eq("venue_city",activity.getVenueCity()).eq("id",activity.getId());
        PageDTO<Activity> page = new PageDTO<>(1,10);
        PageDTO<Activity> page1 = activityMapper.selectPage(page, wrapper);
        return ResponseHelper.build(200, page1);
    

这里有几个参数需要介绍一下。

• @Api 在类上，标明此Controller的用处、
• @ApiOperation 表明此接口的用处
• @ApiImplicitParam 请求一个入参的说明，有name、value、defaultValue等属性
• @ApiImplicitParams 若有多个入参，此是一个数组，把多个ApiImplicitParam放进去即可
• @RequestParam(required=true) 和 @ApiImplicitParam中的必填不同，一个是开发者指定参数必传，一个是swagger调用时必填，但对后台无影响。
• 若入参是一个实体，比如第三个分页查询 ，可以在实体中也注入 swagger 注解，在前端页面也可让开发者了解参数结构

@Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(value = "activity", description = "演出表")
@TableName("activity")
public class Activity implements Serializable 

    private static final long serialVersionUID = -3563130625676560116L;
    @ApiModelProperty(value = "主键ID")
    private Long id;
    @ApiModelProperty(value = "演出名称")
    private String name;
    @ApiModelProperty(value = "演出起始时间")
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    private Date showStartTime;
    @ApiModelProperty(value = "演出结束时间")
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    private Date showEndTime;
    @ApiModelProperty(value = "场地城市")
    private String venueCity;
    @ApiModelProperty(value = "场地名称")
    private String venueName;
    @ApiModelProperty(value = "场地地址")

• @ApiModel 是描述此类的信息
• @ApiModelProperty 是描述字段的信息

5、swagger调试

接口编写好了，我们可以去 localhost:8080/swagger-ui/index.html 页面上去调试。

点击 try it 然后再填入参数，点击 Excute ，即可再返回中看到结果。

弯弯月亮，只为美好的自己。

SpringBoot+Security+Swagger2配置

SpringBoot+Security+Swagger2配置

前言：本来想用Swagger3呢，但是找了好久都没有找到Swagger3的文档，百度也搜不到。这里说的是添加security的登录、登出配置。所以就借用了网上的部分代码做的

1. 首先在pom.xml中添加swagger2的坐标

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

2. 创建一个swagger的配置文件

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger2Config 配置文件
 */
@Configuration
public class Swagger2Config implements WebMvcConfigurer {
    /**
     * 导入配置文件中的值
     */
    @Value("${debugger_tools}")
    private Boolean debuggerTools;
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些借口暴露给Swagger来展现
     * 本例采用指定扫描的包路径来定义指定要建立API的目录
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        		// 这里表示是否启用swagger
                .enable(debuggerTools)
                // 项目前缀
                .apiInfo(new ApiInfoBuilder()
                        .title("*******")//网页标题
                        .description("一个简单的测试")//网页描述
                        .contact(new Contact("tom",null,"[e-mail]"))//用户名，url,email
                        .version("1.00")//接口版本号
                        .build());
    }

}

3. 在security中configure配置，其他配置这里不介绍

/**
 * 拦截请求后的权限设置
 *
 * @param http
 * @throws Exception
 */
@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
            // 设置Swagger2匿名访问
            .antMatchers("/swagger-ui.html", "/webjars/**",
                    "/v2/**", "/swagger-resources/**").permitAll()
}

4. 实现以上两步，即可通过http://IP:端口/项目前缀/swagger-ui.html访问swagger，项目前缀有则写没有则不写；例如http://localhost:8080/swagger-ui.html
5. 细心的朋友会发现：因为Security是自带登录、登出请求的，因此swagger并不会生成这两个请求，因此需要手动去增加这两个请求。也就是这里swagger3中我尚未找到解决办法。在swagger3中这里使用的方法很多都弃用了，也没找到官方文档去解决这个问题。说再多都是废话，最终实现才是目的，因此使用Swagger2，上代码：

import com.fasterxml.classmate.TypeResolver;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.OperationBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiDescription;
import springfox.documentation.service.Operation;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.ApiListingScannerPlugin;
import springfox.documentation.spi.service.contexts.DocumentationContext;
import springfox.documentation.spring.web.readers.operation.CachingOperationNameGenerator;

import java.util.*;

/**
 * 手动添加swagger接口，如登录接口、登录出接口等
 *
 * @author songyinyin
 * @date 2020/6/17 下午 10:03
 */
@Component
public class SwaggerAddtion implements ApiListingScannerPlugin {
    /**
     * Implement this method to manually add ApiDescriptions
     * 实现此方法可手动添加ApiDescriptions
     *
     * @param context - Documentation context that can be used infer documentation context
     * @return List of {@link ApiDescription}
     * @see ApiDescription
     */
    @Override
    public List<ApiDescription> apply(DocumentationContext context) {
        return Arrays.asList(login(),unLogin());
    }
    /**
     * 定义用户名的字段
     * @return
     */
    public Parameter username(){
        return new ParameterBuilder()
                .description("用户名")
                .type(new TypeResolver().resolve(String.class))
                .name("username")
                .parameterType("form")
                .parameterAccess("access")
                .defaultValue("admin")
                .required(true)
                .modelRef(new ModelRef("string"))
                .build();
    }

    /**
     * 定义密码的字段
     * @return
     */
    public Parameter password(){
        return new ParameterBuilder()
                .description("密码")
                .type(new TypeResolver().resolve(String.class))
                .name("password")
                .parameterType("form")
                .parameterAccess("access")
                .defaultValue("admin123")
                .required(true)
                .modelRef(new ModelRef("string"))
                .build();
    }
    /**
     * 定义验证码的字段
     */
    public Parameter code(){
        return new ParameterBuilder()
                .description("验证码")
                .type(new TypeResolver().resolve(String.class))
                .name("code")
                .parameterType("form")
                .parameterAccess("access")
                .required(false)
                .modelRef(new ModelRef("string"))
                .build();
    }
    /**
     * 定义返回消息
     * @return
     */
    public Set<ResponseMessage> responseMessages(){
        Set<ResponseMessage> messages = new HashSet<>();
        messages.add(new ResponseMessageBuilder().code(200).message("ok").build());
        messages.add(new ResponseMessageBuilder().code(401).message("Unauthorized").build());
        messages.add(new ResponseMessageBuilder().code(403).message("Forbidden").build());
        messages.add(new ResponseMessageBuilder().code(404).message("Not Found").build());
        return messages;
    }

    /**
     * 登录请求
     * @return
     */
    public ApiDescription login(){
        Operation loginOperation = new OperationBuilder(new CachingOperationNameGenerator())
                .tags(Collections.singleton("用户接口"))
                .summary("登录")
                .notes("登录")
                .method(HttpMethod.POST)
                .consumes(Collections.singleton(MediaType.APPLICATION_FORM_URLENCODED_VALUE)) // 接收参数格式
                .produces(Collections.singleton(MediaType.APPLICATION_JSON_VALUE)) // 返回参数格式
                .parameters(Arrays.asList(username(),password(),code())) //定义参数
                .responseMessages(responseMessages())
                .build();

        ApiDescription loginApiDescription = new ApiDescription("login", "/login","登录接口",
                Arrays.asList(loginOperation), false);
        return loginApiDescription;
    }
    /**
     * 退出登录请求
     * @return
     */
    public ApiDescription unLogin(){
        Operation unLoginOperation = new OperationBuilder(new CachingOperationNameGenerator())
                .tags(Collections.singleton("用户接口"))
                .summary("登出")
                .notes("登出")
                .method(HttpMethod.GET)
                .produces(Collections.singleton(MediaType.APPLICATION_JSON_VALUE)) // 返回参数格式
                .responseMessages(responseMessages())
                .build();
        ApiDescription unLoginApiDescription = new ApiDescription("logout", "/logout","退出登录接口",
                Arrays.asList(unLoginOperation), false);
        return unLoginApiDescription;
    }
    /**
     * 是否使用此插件
     *
     * @param documentationType swagger文档类型
     * @return true 启用
     */
    @Override
    public boolean supports(DocumentationType documentationType) {
        return DocumentationType.SWAGGER_2.equals(documentationType);
    }
}

7. 在第二步中有一个属性是debuggerTools，说是导入配置文件中的值，是的，正式中swagger是为了方便调试用的，所以在生产环境中是无需启用，因此可以使用配置文件来控制是否启用swagger。可以在不同的环境变量中定义debugger_tools属性值。根据启用不同环境配置，来决定是否启用swagger(SpringBoot如何配置多环境)
   如下：

# 是否启用swagger,postman调试
# application-dev.yml环境
debugger_tools: true


# application-test.yml、application-prod.yml环境
debugger_tools: false

8. 结果，因为我的登录、登出路径是重定义加了/user 。默认没有
   

参考文章：
Security如何配置swagger2
swagger2添加Security登录接口