Toc
  1. 前言
  2. Swagger集成项目
    1. pom引入
    2. Configuration注入
    3. 实现WebMvcConfigurer
    4. 在controller中集成注解
  3. 小问题记录
    1. 注解问题
    2. 与Shiro集成的问题
  4. 离线文档(后续更新)
Toc
0 results found
Espada
Swagger初体验
2019/07/16 Java技术 Swagger

Swagger…现在好像又多了一层台味…

前言

以前刚接触到Swagger,不知道他还能导出成Word、PDF文档,就觉得Postman+文档够用了,现在觉得代码中集成这样的框架,在初期能够方便很多。

  • 功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
  • 条理清晰 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
  • 整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

Swagger集成项目

Swagger本身是一种规范,而SpringFox-Swagger是专注于Spring生态的实现,Spring-Swagger-UI则是对Swagger-UI的封装。

代码整整合也非常的简单,首先是pom引入:

pom引入

<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.6.1version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.6.1version>
dependency>
<dependency>
<groupId>io.github.swagger2markupgroupId>
<artifactId>swagger2markupartifactId>
<version>1.3.1version>
dependency>

其中swagger2markup是用于Swagger导出PDF/HTML的依赖,离线文档之后再更新,目前还有点问题。

application.properties中加这么一句spring.resources.static-locations=classpath:/static/,不然swagger-ui.html这个页面会被拦截。

Configuration注入

/**
* @ClassName SwaggerConfiguration
* @Description TODO
* @Author MatthewHan
* @Date 2019/7/16 16:15
* @Version 1.0
**/
@Configuration
public class SwaggerConfiguration {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 这是注意的代码
.apis(RequestHandlerSelectors.basePackage("com.zrtg.ldapsync.common.action"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("ldap-sync接口文档")
.description("用于大院LDAP服务器同步无纸化办公组织架构")
.termsOfServiceUrl("http://gitlab.zrtg.com/996team/ldap-sync")
.version("1.0")
.build();
}

}
  • 其中basePackage中的一般配置controller的路径,paths属性进行过滤,apis属性可以设置扫描包,或者通过注解的方式标识;通过enable属性,可以在application-{profile}.properties文件中设置相应值,主要用于控制生产环境不生成接口文档。另外还有groupName()进行分组,比如高级客户、~~低端人口(雾)~~之类的分组。
  • apiInfo中包装了文档的titledescriptionversion这些信息。

然后在Springboot的入口类中加上@EnableSwagger2表示开启Swagger2。

完成这些步骤后,发现其实访问https://localhost/swagger-ui.html并没有swagger页面,原因是在所映射的地址在SpringBoot静态资源文件夹下找不到。所以需要定义一个拦截器来放行。

实现WebMvcConfigurer

/**
* @ClassName WebMvcConfiguration
* @Description 用于Swagger UI显示
* @Author MatthewHan
* @Date 2019/7/16 16:37
* @Version 1.0
**/
@Configuration
public class WebMvcConfiguration implements WebMvcConfigurer {

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {

registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/templates/**")
.addResourceLocations("classpath:/META-INF/resources/templates/");
}
}

我们只需要重写addResourceHandlers方法即可,通过addResourceHandler添加映射路径,然后再通过addResourceLocations来指定路径。addResourceLocations指的是文件放置的目录,addResoureHandler指的是对外暴露的访问路径。

在controller中集成注解

注解 描述
@Api 修饰整个类,描述Controller的作用
@ApiOperation 描述一个类的一个方法,或者说一个接口
@ApiParam 单个参数描述
@ApiModel 用对象来接收参数
@ApiProperty 用对象接收参数时,描述对象的一个字段
@ApiResponse HTTP响应其中1个描述
@ApiResponses HTTP响应整体描述
@ApiIgnore 使用该注解忽略这个API
@ApiError 发生错误返回的信息
@ApiImplicitParam 一个请求参数
@ApiImplicitParams 多个请求参数

最后通过浏览器来访问https://localhost/swagger-ui.html如下图:

Swagger-UI

Method类型、相关描述、Example、StatusCode都会自动帮你生成。

小问题记录

注解问题

直接在通过@PathVariable注解的参数在Swagger中用了@ApiImplicitParam,发现在页面中请求是有问题的,这个注解应该对应的是func(@Param("arg") String arg)方法,实际上正确的用法是@ApiParam。类似下图代码:

/**
* 测试
* 用于添加一个ou,例如:department,employee
* @param ou
* @return
*/
@ApiOperation(value = "添加一个OU")
@ApiParam(name = "ou", value = "组织单元", required = true)
@PostMapping("/add-ldap-ou/{ou}")
public BaseResult addLdapOu(@PathVariable("ou")String ou){
...
}

与Shiro集成的问题

通过无拦截测试总结了如下的资源路径是swagger在渲染页面时的必需。如果工程中包含了Shiro安全框架,需要对swagger进行放行。

// 设置拦截器
Map filterChainDefinitionMap = new LinkedHashMap<>();
// swagger放行
filterChainDefinitionMap.put("/swagger-ui.html", "anon");
filterChainDefinitionMap.put("/swagger-resources/**", "anon");
filterChainDefinitionMap.put("/v2/**", "anon");
filterChainDefinitionMap.put("/webjars/**", "anon");
filterChainDefinitionMap.put("/configuration/**", "anon");

ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean();
shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);

在你的Shiro配置类中添加如上路径即可。

离线文档(后续更新)

龙鸣
"老罗"
本文作者:Espada
版权声明:本文首发于Espada的博客,转载请注明出处!