springboot集成Swagger-knife4j（三）

最新推荐文章于 2024-04-24 09:53:59 发布

qq_250056868

最新推荐文章于 2024-04-24 09:53:59 发布

阅读量1.1k

点赞数 1

分类专栏： springboot 文章标签： java spring boot

本文链接：https://blog.csdn.net/qq_41604890/article/details/108875865

版权

springboot 专栏收录该内容

40 篇文章 4 订阅

订阅专栏

在springboot集成Swagger-knife4j接口文档

本文章内容很多来自狂神说视频学习
狂神说Swagger学习推荐视频: https://www.bilibili.com/video/BV1PE411i7CV?p=48.

pom.xml配置依赖

    <dependencies>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.49</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>
    </dependencies>

SwaggerConfig

package com.zm.web.Config;

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket login() {
        return docket("测试", "com.zm.web.controller");
    }

    public Docket docket(String groupName, String basePackage) {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(groupName)
                .apiInfo(apiInfo())
                .select()
                // 配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                // 配置接口过滤规则
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("title")
                .description("description")
                .license("license")
                .licenseUrl("licenseUrl")
                .termsOfServiceUrl("termsOfServiceUrl")
                .contact(new Contact("name", "url", "email"))
                .version("version")
                .build();
    }
}

RequestHandlerSelectors配置扫描的接口

RequestHandlerSelectors.any() // 扫描所有，项目中的所有接口都会被扫描到
RequestHandlerSelectors.none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
RequestHandlerSelectors.withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
RequestHandlerSelectors.withClassAnnotation(final Class<? extends Annotation> annotation)
RequestHandlerSelectors.basePackage(final String basePackage) // 根据包路径扫描接口

PathSelectors配置过滤规则

PathSelectors.any() // 任何请求都扫描
PathSelectors.none() // 任何请求都不扫描
PathSelectors.regex(final String pathRegex) // 通过正则表达式控制
PathSelectors.ant(final String antPattern) // 通过ant()控制

HttpConverterConfig

package com.zm.web.Config;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.serializer.SerializerFeature;
import com.alibaba.fastjson.support.config.FastJsonConfig;
import com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import java.nio.charset.Charset;
import java.util.ArrayList;
import java.util.List;

@Configuration
public class HttpConverterConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }


    //使用阿里 FastJson 作为JSON MessageConverter
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();
        List<MediaType> supportedMediaTypes = new ArrayList<>();
        supportedMediaTypes.add(MediaType.APPLICATION_JSON);
        supportedMediaTypes.add(MediaType.APPLICATION_JSON_UTF8);
        supportedMediaTypes.add(MediaType.APPLICATION_ATOM_XML);
        supportedMediaTypes.add(MediaType.APPLICATION_FORM_URLENCODED);
        supportedMediaTypes.add(MediaType.APPLICATION_OCTET_STREAM);
        supportedMediaTypes.add(MediaType.APPLICATION_PDF);
        supportedMediaTypes.add(MediaType.APPLICATION_RSS_XML);
        supportedMediaTypes.add(MediaType.APPLICATION_XHTML_XML);
        supportedMediaTypes.add(MediaType.APPLICATION_XML);
        supportedMediaTypes.add(MediaType.IMAGE_GIF);
        supportedMediaTypes.add(MediaType.IMAGE_JPEG);
        supportedMediaTypes.add(MediaType.IMAGE_PNG);
        supportedMediaTypes.add(MediaType.TEXT_EVENT_STREAM);
        supportedMediaTypes.add(MediaType.TEXT_HTML);
        supportedMediaTypes.add(MediaType.TEXT_MARKDOWN);
        supportedMediaTypes.add(MediaType.TEXT_PLAIN);
        supportedMediaTypes.add(MediaType.TEXT_XML);
        converter.setSupportedMediaTypes(supportedMediaTypes);
        converter.setDefaultCharset(Charset.forName("UTF-8"));
        FastJsonConfig config = new FastJsonConfig();
        JSON.DEFFAULT_DATE_FORMAT = "yyyy-MM-dd HH:mm:ss";
        config.setSerializerFeatures(SerializerFeature.WriteDateUseDateFormat);//格式化时间
        converter.setFastJsonConfig(config);
        // 把FastJsonHttpMessageConverter放到Jackson的前面去
        // 这个list是个ArrayList 所以我们要么就放在首位（不建议）,
        // 而converters.indexOf() 因为人家是new的 所以肯定是找不到此对象的位置的 所以采用遍历的方式吧
        int jacksonIndex = 0;
        for (int i = 0; i < converters.size(); i++) {
            if (converters.get(i) instanceof MappingJackson2HttpMessageConverter) {
                jacksonIndex = i;
                break;
            }
        }
        // 添加在前面
        converters.add(jacksonIndex, converter);
    }

}

常用注解

@Api(tags = "xxx模块说明")	作用在模块类上
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

常用@ApiModelProperty注解

@ApiModelProperty(value = “”, example = “”, position = 1)
value(String) 此属性的可读概要
example(String) 举例
position(int) 在模型中显式排序属性。
required(boolean) 无论属性是否必需，默认为false。
access(String) 指定一个可选的访问值，以便在Filter实现中进行过滤。
allowableValues(String) 如果可以设置的值受到限制，则可以在此处设置它们。
dataType 支持的数据类型
hidden(boolean) 允许在swagger模型定义中将模型属性标记为隐藏
notes(String) 长描述
name(String) 重写属性名字

API统一回调

package com.zm.common.util;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;

@ApiModel
public class ApiResult<T> implements Serializable {

    @ApiModelProperty(value = "回调数据")
    private T data;

    @ApiModelProperty(value = "版本号")
    private String vision;

    @ApiModelProperty(value = "状态码")
    private String code;

    @ApiModelProperty(value = "消息提示")
    private String msg;

    @ApiModelProperty(value = "数据结果集")
    public T getData() {
        return data;
    }

    public String getVision() {
        return vision;
    }

    public String getCode() {
        return code;
    }

    public String getMsg() {
        return msg;
    }

    public ApiResult<T> setData(T data) {
        this.data = data;
        return this;
    }

    public ApiResult<T> setVision(String vision) {
        this.vision = vision;
        return this;
    }

    public ApiResult<T> setCode(String code) {
        this.code = code;
        return this;
    }

    public ApiResult<T> setMsg(String msg) {
        this.msg = msg;
        return this;
    }

    /**
     * @Description    成功回调
     * @param data     回调数据
     * @param vision   版本号
     * @return
     */
    public static ApiResult successMsg(Object Object, String vision) {
        return new ApiResult().setCode("200").setMsg("scuess").setData(Object).setVision(vision);
    }


}

API接收或者返回的具体类

package com.zm.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel
public class User {
    @ApiModelProperty(value = "id")
    private Integer id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "爱好")
    private String skill;
    @ApiModelProperty(value = "评价")
    private String evaluate;
    @ApiModelProperty(value = "成绩")
    private Integer fraction;

}

API层

package com.zm.web.controller;

import com.zm.common.util.ApiResult;
import com.zm.entity.User;
import com.zm.service.UserService;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Autowired
    private UserService userService;
    
    @PostMapping("/hello")
    @ApiOperation(value = "hello" ,httpMethod = "POST")
    public ApiResult<User> hello(@RequestBody User userVo) {
        System.out.println("请求参数："+userVo);
        User 小明 = userService.selectUserInfoByName("小明");
        return ApiResult.successMsg(小明,"1");
    }

}

启动项目，访问地址http://127.0.0.1:8080/doc.html

在这里插入图片描述

配置Swagger开关

1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

2、如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean b = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

本文章很多内容来自狂神说视频学习
狂神说Swagger学习推荐视频: https://www.bilibili.com/video/BV1PE411i7CV?p=48.

qq_250056868

关注

1
点赞
踩
2

收藏

觉得还不错? 一键收藏
0
评论
springboot集成Swagger-knife4j（三）

在springboot集成Swagger-knife4j接口文档pom.xml配置依赖 <dependencies> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.49</version&
复制链接

扫一扫