Swagger2配置方式可以分为两种:基于配置类的配置和基于XML文件的配置。
基于配置类的配置
- 开始之前,需要在pom.xml文件中引入Swagger2依赖:
<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>
- 添加Swagger2配置类,示例代码如下:
“`java
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2 Demo API")
.description("This is a sample Spring Boot RESTful service using Swagger2.")
.version("1.0.0")
.build();
}
}
“`
- 然后,在启动类上添加@EnableSwagger2注解,示例代码如下:
“`java
@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
“`
- 最后,在浏览器中访问 http://localhost:8080/swagger-ui.html,可以看到Swagger2管理页面,可以测试API接口了。
基于XML文件的配置
-
开始之前,先在pom.xml文件中引入Swagger2依赖,同基于配置类的配置。
-
在resources目录下新建一个名为swagger-config.xml的文件,并添加如下内容:
“`xml
<!--开启注解-->
<context:component-scan base-package="com.example.demo.controller" />
<!-- 关闭默认的安全配置 -->
<swaggger:security>
<swaggger:securityConfiguration />
</swaggger:security>
<!-- 配置文档信息 -->
<swaggger:documentation>
<swaggger:apiInfo>
<swaggger:title>Swagger2 Demo API</swaggger:title>
<swaggger:description>This is a sample Spring Boot RESTful service using Swagger2.</swaggger:description>
<swaggger:version>1.0.0</swaggger:version>
</swaggger:apiInfo>
</swaggger:documentation>
“`
此处省略了头文件信息和命名空间。
-
在启动类上添加@ImportResource(“classpath:swagger-config.xml”)注解,告诉Spring Boot要导入该配置文件。
-
最后,在浏览器中访问 http://localhost:8080/swagger-ui.html,也可以看到Swagger2管理页面,可以测试API接口了。
以上就是Swagger2配置方式的完整攻略,下面将给出两个示例说明。
示例一:
假设你有一个名为UserController的RESTful控制器,在处理请求时需要使用Swagger2进行API接口文档管理。则需要在项目中创建SwaggerConfig类,如下所示:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2 Demo API")
.description("This is a sample Spring Boot RESTful service using Swagger2.")
.version("1.0.0")
.build();
}
}
其中,@Configuration注解表示这是一个配置类,@EnableSwagger2注解表示启用Swagger2支持。Docket对象是Swagger核心配置,通过它可以配置API接口信息、安全信息等。在api()方法中,我们选择过滤的接口路径是com.example.demo.controller,通过PathSelectors.any()方法可以剔除所有不是以该路径开头的接口。在最后,我们使用apiInfo()方法来构建API接口文档相关信息。
示例二:
在上面的示例中,我们使用了SwaggerConfig类来配置Swagger2支持,但当你的应用中存在多个Swagger2配置类时,可能会导致应用部署失败或API文档不完整。这时,你可以在启动类上使用@Import注解来导入SwaggerConfig类,示例如下:
@SpringBootApplication
@EnableSwagger2
@Import({SwaggerConfig.class})
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
在上面的示例中,通过@Import注解导入了SwaggerConfig类,这样就可以在启动类中统一管理应用中的Swagger2配置。