Swagger 修改默认配置
目录
- swagger配置
- 使用Docket
- 修改一下swagger的默认数据
- 运行项目，访问http://localhost:8080/swagger-ui.html
- 额外加一点东西
swagger配置
package com.sky.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 使用swagger需要创建一个配置类，并开启swagger配置
* ps：swagger和 swagger2 不能通用
*
* 步骤：
* 1.将swaggerConfig注册到ioc容器中
* 2.开启swagger2功能
* 3.运行项目，访问swagger-ui.html
*/
@Configuration // 就是@Component
@EnableSwagger2 // 开启swagger
public class Swagger2Config {
}
那我们要怎么更改swagger的默认配置呢？
先看 @EnableSwagger2
//
// Source code recreated from a .class file by IntelliJ IDEA
// (powered by Fernflower decompiler)
//
package springfox.documentation.swagger2.annotations;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.context.annotation.Import;
import springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration;
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@Documented
@Import({Swagger2DocumentationConfiguration.class}) // 导入指定类
public @interface EnableSwagger2 {
}
该类的注解上有==@Import({Swagger2DocumentationConfiguration.class})==，导入了 Swagger2DocumentationConfiguration.class 这个类，继续看一下这个类是干哈的。
//
// Source code recreated from a .class file by IntelliJ IDEA
// (powered by Fernflower decompiler)
//
package springfox.documentation.swagger2.configuration;
import ...
@Configuration // 该类是一个配置类
@Import({SpringfoxWebMvcConfiguration.class, SwaggerCommonConfiguration.class})
@ComponentScan(
basePackages = {"springfox.documentation.swagger2.mappers"}
)
@ConditionalOnWebApplication
public class Swagger2DocumentationConfiguration {
public Swagger2DocumentationConfiguration() {
}
@Bean
public JacksonModuleRegistrar swagger2Module() {
return new Swagger2JacksonModule();
}
@Bean
public HandlerMapping swagger2ControllerMapping(Environment environment, DocumentationCache documentationCache, ServiceModelToSwagger2Mapper mapper, JsonSerializer jsonSerializer) {
return new PropertySourcedRequestMappingHandlerMapping(environment, new Swagger2Controller(environment, documentationCache, mapper, jsonSerializer));
}
}
我们关注这里 @Import({SpringfoxWebMvcConfiguration.class, SwaggerCommonConfiguration.class})。
- SpringfoxWebMvcConfiguration.class：swagger的web配置
- SwaggerCommonConfiguration.class：该类用来扫描swagger的一些类
SpringfoxWebMvcConfiguration.class是我们要关注的类。
/*
*
* Copyright 2015-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*
*/
package springfox.documentation.spring.web;
import ...
@Configuration
@Import({ ModelsConfiguration.class })
@ComponentScan(basePackages = {
"springfox.documentation.spring.web.scanners",
"springfox.documentation.spring.web.readers.operation",
"springfox.documentation.spring.web.readers.parameter",
"springfox.documentation.spring.web.plugins",
"springfox.documentation.spring.web.paths"
})
@EnablePluginRegistries({ DocumentationPlugin.class,
ApiListingBuilderPlugin.class,
OperationBuilderPlugin.class,
ParameterBuilderPlugin.class,
ExpandedParameterBuilderPlugin.class,
ResourceGroupingStrategy.class,
OperationModelsProviderPlugin.class,
DefaultsProviderPlugin.class,
PathDecorator.class,
ApiListingScannerPlugin.class
})
public class SpringfoxWebMvcConfiguration {...}
在==@EnablePluginRegistries==注解中有一个类 DocumentationPlugin.class ，该类是一个接口，该接口有一个实现类，Docket，Docket 类可以对swagger进行一些参数配置。
/**
* A builder which is intended to be the primary interface into the Springfox framework.
* Provides sensible defaults and convenience methods for configuration.
* 一个构建器，旨在成为Springfox框架的主要接口。 提供合理的默认设置和便捷的配置方法。
*/
public class Docket implements DocumentationPlugin {
private ApiInfo apiInfo = ApiInfo.DEFAULT;
public Docket apiInfo(ApiInfo apiInfo) {
this.apiInfo = defaultIfAbsent(apiInfo, apiInfo);
return this;
}
}
使用Docket
创建一个Docket，并添加到ioc容器中
@Configuration // 就是@Component
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket docket(){
return new Docket();// 需要传一个参数DocumentationType documentationType
}
}
new Docket() 需要我们传一个 DocumentationType 类型的对象，那我们就进 DocumentationType 看一下怎么创建这个对象。
package springfox.documentation.spi;
import ...
public class DocumentationType extends SimplePluginMetadata {
public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
private final MediaType mediaType;
/**
* Creates a new instance of {@code SimplePluginMetadata}.
*
* @param name must not be {@literal null}.
* @param version must not be {@literal null}.
* @param mediaType must not be {@literal null}
*/
public DocumentationType(String name, String version, MediaType mediaType) {
super(name, version);
this.mediaType = mediaType;
}
public DocumentationType(String name, String version) {
this(name, version, MediaType.APPLICATION_JSON);
}
public ...
DocumentationType 类里面有 3 个静态属性，2 个构造器，仔细观察会发现那 3 个静态属性就是 DocumentationType 类型的对象，那我们省力一点，用这 3 个对象中的一个当做参数传给 Docket 好了。
那么，选哪个呢？
这里我们用的是swagger2，那么应该选择这个
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
给Docket传入参数：
@Configuration // 就是@Component
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}
}
修改一下swagger的默认数据
Docket 类中有一个方法
/*
如果ApiInfo为空，就返回一个默认的 ApiInfo 对象
*/
public Docket apiInfo(ApiInfo apiInfo) {
this.apiInfo = defaultIfAbsent(apiInfo, apiInfo);
return this;
}
那么ApiInfo的默认对象是哪个呢？
ctrl+左键 点击 this.apiInfo，找到这一行代码
private ApiInfo apiInfo = ApiInfo.DEFAULT;
继续点击 ApiInfo.DEFAULT，ApiInfo 类
package springfox.documentation.service;
import ...
public class ApiInfo {
public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
public static final ApiInfo DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
private final String version;
private final String title;
private final String description;
private final String termsOfServiceUrl;
private final String license;
private final String licenseUrl;
private final Contact contact;
private final List<VendorExtension> vendorExtensions;
/**
* Deprecated in favor of richer contact object
* @deprecated @since 2.4.0
*
* @param title title
* @param description description
* @param version version
* @param termsOfServiceUrl terms of service
* @param contactName contact name
* @param license licence text
* @param licenseUrl license url
*/
@Deprecated
public ApiInfo(
String title,
String description,
String version,
String termsOfServiceUrl,
String contactName,
String license,
String licenseUrl) {
this(title, description, version, termsOfServiceUrl, new Contact(contactName, "", ""), license, licenseUrl, new ArrayList<VendorExtension>());
}
/**
* Default contstructor
* @param title title
* @param description description
* @param version version
* @param termsOfServiceUrl termsOfServiceUrl
* @param contact contact
* @param license license
* @param licenseUrl license url
* @param vendorExtensions vendor extensions
*/
public ApiInfo(
String title,
String description,
String version,
String termsOfServiceUrl,
Contact contact,
String license,
String licenseUrl,
Collection<VendorExtension> vendorExtensions) {
this.title = title;
this.description = description;
this.version = version;
this.termsOfServiceUrl = termsOfServiceUrl;
this.contact = contact;
this.license = license;
this.licenseUrl = licenseUrl;
this.vendorExtensions = newArrayList(vendorExtensions);
}
public ...
}
在类中可以看到ApiInfo.DEFAULT是一个静态ApiInfo的对象，那我们模仿一下这个静态对象，自定义一个我们自己的ApiInfo对象。
package com.sky.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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* 使用swagger需要创建一个配置类，并开启swagger配置
* ps：swagger和 swagger2 不能通用
*
* 步骤：
* 1.将swaggerConfig注册到ioc容器中
* 2.开启swagger2功能
* 3.运行项目，访问swagger-ui.html
*/
@Configuration // 就是@Component
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
@Bean
public ApiInfo apiInfo(){
ApiInfo apiInfo = new ApiInfo(
"sky的swagger文档" //标题
, "天空蓝蓝的" // 描述
, "v1.0" // 版本信息
, "ttps://blog.csdn.net/Sky_for_me" // 一个url地址
, DEFAULT_CONTACT// 作者信息对象
, "Apache 2.0" // 开源版本号
, "http://www.apache.org/licenses/LICENSE-2.0" // 开源版本号地址
, new ArrayList<VendorExtension>());
return apiInfo;
}
}
在自定义的过程中，发现有个参数在报错 DEFAULT_CONTACT，在ApiInfo类中可以看到这个参数的信息，该参数是一个包含作者信息的对象
// 作者的信息
public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
那我们还是照葫芦画瓢，模仿自己写一个
@Bean
public ApiInfo apiInfo(){
Contact contact = new Contact("sky", "https://blog.csdn.net/Sky_for_me", "[email protected]");
ApiInfo apiInfo = new ApiInfo(
"sky的swagger文档" //标题
, "天空蓝蓝的" // 描述
, "v1.0" // 版本信息
, "ttps://blog.csdn.net/Sky_for_me" // 一个url地址
, contact // 作者信息对象
, "Apache 2.0" // 开源版本号
, "http://www.apache.org/licenses/LICENSE-2.0" // 开源版本号地址
, new ArrayList<VendorExtension>());
return apiInfo;
}
自定义swagger信息完毕，运行项目看一看情况。
运行项目，访问http://localhost:8080/swagger-ui.html
自定义信息成功！
额外加一点东西
public class Docket implements DocumentationPlugin {
/**
* 这个是分组的组名
*/
public static final String DEFAULT_GROUP_NAME = "default";
public ...
}
这个↓
参考资料：https://www.bilibili.com/video/BV1PE411i7CV?p=48