文章目录
参考
maven的部分内容
不同package引用
每个package都有一个pom,不同的包之间通过pom引用
pom写法
各种包引入,参见参考文章
其中几个比较重要的引入说明
根pom
<swagger-version>2.9.2</swagger-version>
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger-version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger-version}</version>
</dependency>
web pom:
<dependencies>
<!--thrift-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
</dependencies>
<build>
<finalName>${project.artifactId}-${project.version}</finalName>
<!--资源文件目录,这里与SpringBoot启动息息相关,从该目录中找启动文件,比如application-boe.yml的位置-->
<resources>
<resource>
<directory>src/main/java</directory>
<includes>
<include>**/*.yml</include>
<include>**/*.xml</include>
</includes>
<filtering>false</filtering>
</resource>
<resource>
<directory>src/main/resources/base</directory>
</resource>
<resource>
<directory>src/main/resources/${conf-dir}</directory>
</resource>
</resources>
<!--测试资源目录-->
<testResources>
<testResource>
<directory>src/main/resources/base</directory>
</testResource>
<testResource>
<directory>src/main/resources/${conf-dir}</directory>
</testResource>
</testResources>
<plugins>
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.6</version>
<configuration>
<apiSources>
<apiSource>
<!-- 支持springMVC -->
<springmvc>true</springmvc>
<!-- 你的web项目Controller包名 -->
<locations>com.bytedance.cg.lark.crm.web.controller</locations>
<!-- 协议 -->
<schemes>http,https</schemes>
<!-- 所在主机,可以为空 -->
<host>localhost:8030</host>
<!-- web项目Context Path -->
<basePath>/</basePath>
<!-- 要在主页显示你的API的 整体信息的,相当于是标题 -->
<info>
<title>接口文档</title>
<version>v1</version>
<description>API</description>
</info>
<!-- 在这里定义导出的swagger.json文件路径,调整构建脚本会用到 -->
<!-- 点击compile之后会在如下目录中打印出swagger.json文件 -->
<swaggerDirectory>${basedir}/interface</swaggerDirectory>
</apiSource>
</apiSources>
</configuration>
<!-- 这里很重要,简单说就是配置在maven的compile生命周期执行时触发swagger插件的generate命令 -->
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
其中关于资源文件部分的一个坑:
配置文件找不到的问题:https://blog.csdn.net/lovequanquqn/article/details/85017533
某个class文件属于哪个包
IDE定位就可以看到上层的包结构
SpringBoot工程启动
启动类文件
@Slf4j
@EnableSwagger2
@EnableCaching
@EnableAsync
@RegisterHttpService
@EnableThriftClients({
@ThriftClient(psm = "", basePackage =
"" ),
})
@SpringBootApplication(scanBasePackages = {"com.a.b"})
public class WebApplication {
public static void main(String[] args) {
System.setProperty("spring.devtools.restart.enabled", "false");
TimeZone.setDefault(TimeZone.getTimeZone("GMT+0"));
SpringApplication.run(WebApplication.class, args);
}
}
如果没有写这个文件,会报错:未发现app.yml文件的错误。
实际上app.yml文件即便配置了,没有启动类也会报这个错误。
app.yml文件配置
applicationArguments:
- --spring.profiles.active=$profile
- --server.port=$PORT
jvmOptions:
- $DEBUG
- -Xms4096m
- -Xmx4096m
- -Xmn2048m
- -XX:SurvivorRatio=15
- -XX:+UseParNewGC
- -XX:ParallelGCThreads=4
- -XX:MaxTenuringThreshold=15
- -XX:+UseConcMarkSweepGC
- -XX:+UseCMSInitiatingOccupancyOnly
- -XX:+ScavengeBeforeFullGC
- -XX:+UseCMSCompactAtFullCollection
- -XX:+CMSParallelRemarkEnabled
- -XX:CMSFullGCsBeforeCompaction=9
- -XX:CMSInitiatingOccupancyFraction=60
- -XX:+CMSClassUnloadingEnabled
- -XX:SoftRefLRUPolicyMSPerMB=0
- -XX:-ReduceInitialCardMarks
- -XX:CMSInitiatingPermOccupancyFraction=70
- -XX:-OmitStackTraceInFastThrow
- -XX:+PrintGCDetails
- -Xloggc:/opt/log/tiger/gc.log
- -XX:+PrintGCTimeStamps
Resource中application.yml配置
所有这一类注解的依赖:@Value("${pigeon.templateId.phoneCall}")
其他的比如:引用的包(已经加到了webapplication扫描文件中)依赖了redis/MySQL,就必须在配置文件中加入redis/MySQL的配置
如果要避免在配置文件中加入这类配置,且确定引用时候不需要依赖这些附件,可以如下写:
<dependency>
<groupId>com.a.cg</groupId>
<artifactId>multi-a-b-base</artifactId>
<exclusions>
<exclusion>
<artifactId>mysql-starter</artifactId>
<groupId>com.bytedance</groupId>
</exclusion>
</exclusions>
</dependency>
webConfig配置
@Configuration
public class WebConfig extends WebMvcConfigurerAdapter {
private static final String[] NO_LOGIN_WHITELIST = {
// exclude swagger
"/swagger*/**",
// default 404
"/error"
};
/**
* getPage接口用于自定义上报监控数据
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new LogIDInjectHandlerInterceptor()).excludePathPatterns(NO_LOGIN_WHITELIST);
}
}
swagger配置
@Configuration
@EnableSwagger2
public class SwaggerConf implements InitializingBean {
@Value("${swagger.enable}")
private boolean enableSwagger;
@Autowired
ConfigurableBeanFactory beanFactory;
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXX系统")
.description("")
.termsOfServiceUrl("")
.version("1.0")
.build();
}
private List<Parameter> commonParameters() {
List<Parameter> parameters = Lists.newArrayList();
parameters.add(new ParameterBuilder()
.name(ContextConstant.LOGIN_EMPLOYEE_ID.replace("_", "-"))
.description("用户ID")
.modelRef(new ModelRef("long"))
.parameterType("header")
.required(true)
.defaultValue("XXXXXX")
.build());
parameters.add(new ParameterBuilder()
.name(ContextConstant.TIME_ZONE.replace("_", "-"))
.description("时区信息")
.modelRef(new ModelRef("string"))
.parameterType("header")
.scalarExample("GMT+8:00")
.required(false)
return parameters;
}
@Override
public void afterPropertiesSet() {
String basePackageName = BASE_PACKAGE_FORMAT;
Docket docketInstance = new Docket(DocumentationType.SWAGGER_2)
.enable(enableSwagger)
.apiInfo(apiInfo())
.groupName("")
.select()
.apis(RequestHandlerSelectors.basePackage(basePackageName))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(commonParameters());
beanFactory.registerSingleton("project." + DOCKET_BEAN_SUFFIX, docketInstance);
}
}
各种配置文件拷贝入resources文件中
注意yml文件内容要包含所有必要的属性配置,否则启动时候将报错:no properties。
比如:配置了redis启动,但是没有在配置文件中加入redis cluster等必填启动项,就会报这个错误。
swagger无法展示api
由于包扫描路径配置不对导致
Spring配置
debug的配置
IDE services:https://blog.csdn.net/Andy5789/article/details/106781950
完成如上内容,就可以开始debug并查看swagger页面了。