当前位置：首页 > news >正文

后端项目开发：集成接口文档（swagger-ui）

news 2025/6/27 8:11:35

swagger集成文档具有功能丰富、及时更新、整合简单，内嵌于应用的特点。

由于后台管理和前台接口均需要接口文档，所以在工具包构建BaseSwaggerConfig基类。
1.引入依赖

 <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配置类。

/*** Swagger基础配置*/
public abstract class BaseSwaggerConfig {@Beanpublic Docket createRestApi() {SwaggerProperties swaggerProperties = swaggerProperties();Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo(swaggerProperties)).select().apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage())).paths(PathSelectors.any()).build();if (swaggerProperties.isEnableSecurity()) {docket.securitySchemes(securitySchemes()).securityContexts(securityContexts());}return docket;}private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {return new ApiInfoBuilder().title(swaggerProperties.getTitle()).description(swaggerProperties.getDescription()).contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail())).version(swaggerProperties.getVersion()).build();}private List<ApiKey> securitySchemes() {//设置请求头信息List<ApiKey> result = new ArrayList<>();ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");result.add(apiKey);return result;}private List<SecurityContext> securityContexts() {//设置需要登录认证的路径List<SecurityContext> result = new ArrayList<>();result.add(getContextByPath("/*/.*"));return result;}private SecurityContext getContextByPath(String pathRegex) {return SecurityContext.builder().securityReferences(defaultAuth()).forPaths(PathSelectors.regex(pathRegex)).build();}private List<SecurityReference> defaultAuth() {List<SecurityReference> result = new ArrayList<>();AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;result.add(new SecurityReference("Authorization", authorizationScopes));return result;}/*** 自定义Swagger配置*/public abstract SwaggerProperties swaggerProperties();
}

将需要配置的字段提取出来，单独作为一类

/*** Swagger自定义配置*/
@Data
@EqualsAndHashCode(callSuper = false)
@Builder
public class SwaggerProperties {/*** API文档生成基础路径*/private String apiBasePackage;/*** 是否要启用登录认证*/private boolean enableSecurity;/*** 文档标题*/private String title;/*** 文档描述*/private String description;/*** 文档版本*/private String version;/*** 文档联系人姓名*/private String contactName;/*** 文档联系人网址*/private String contactUrl;/*** 文档联系人邮箱*/private String contactEmail;
}

前台接口和后台管理的包的配置，只需要继承重写该类就行了

/*** Swagger API文档相关配置*/
@Configuration
@EnableSwagger2
public class SwaggerConfig extends BaseSwaggerConfig {@Overridepublic SwaggerProperties swaggerProperties() {return SwaggerProperties.builder().apiBasePackage("com.example.admin").title("后台管理系统").description("后台相关接口文档").contactName("author").version("1.0").enableSecurity(true).build();}
}