swagger2文档自动生成使用
第一步需要搭建一个项目,本例使用的时SpringBoot纯注解类型的项目结构。
首先需要在pom文件引入相关的一个依赖。这个使用的是SpringBoot建议使用SpringBoot的封装的swagger的stater依赖。
<dependency>
<groupId>com.didispace</groupId>
<artifactId>spring-boot-starter-swagger</artifactId>
<version>1.1.0.RELEASE</version>
</dependency>
第二步:
需要在SpringBoot启动类的同级下新建一个swagger配置类,并配置相关内容。`
@Configuration
@EnableSwagger2
public class SwaggerConfig {
public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.cym.controller";
public static final String VERSION = "1.0.0";
ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger API")
.description("This is to show api description")
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.termsOfServiceUrl("")
.version(VERSION)
.contact(new Contact("","", "miaorf@outlook.com"))
.build();
}
@Bean
public Docket customImplementation(){
return new Docket(DocumentationType.SPRING_WEB)
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.build()
.directModelSubstitute(LocalDate.class, java.sql.Date.class)
.directModelSubstitute(DateTime.class, java.util.Date.class)
.apiInfo(apiInfo());
}
}
配置完成之后,使用@ApiOperation注解对接口信息进行描述,使用@ApiImplicitParam注解对单个参数进行描述,@ApiImplicitParams使用这个注解对多个参数进行描述,使用@ApiIgnore这个注解忽略某个接口,不然其显示在swagger文档中。本地启动完成后,完整访问路径为:http://localhost:8080/swagger-ui.html#/
我们需要在生产环境中拦截访问这个url,可以开个接口提供给测试环境,进行开发,测试。生产环境进行拦截。接口不暴露到swagger文档中。
@ApiOperation(value="用户注册",notes="用户注册账号和密码")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
@ApiImplicitParam(name = "passWord", value = "用户密码", required = true, dataType = "String")
})
@RequestMapping(value="/register",method=RequestMethod.POST)
public WebResult<Object> userRegister(String userName
,String passWord){
return new WebResult<Object> ("0", "success", null);
}
@ApiIgnore
@RequestMapping(value="/swagger",method=RequestMethod.GET)
public void redictSwagger(HttpServletRequest request,HttpServletResponse response){
StringBuffer url = new StringBuffer();
url.append(request.getScheme()+"://");
url.append(request.getServerName());
url.append(":"+request.getServerPort());
url.append("/swagger-ui.html");
CommonUtil.redirectURL(url.toString(), response);
}
public static void redirectURL(String url,HttpServletResponse response){
try {
log.info("开始重定向");
response.sendRedirect(url);
log.info("重定向成功URL="+url);
} catch (Exception e) {
log.info("重定向URL="+url+"发生异常...");
}
}
swagger文档生成接口到这里就结束了,喜欢的同学可以给我点个赞,关注我。以后会为大家带来更好的技术小姿势。需要注意的是,springMVC类型的项目,可以使用,springfox-swagger-ui,springfox-swagger2这两个依赖 ,
可以去Maven搜索一下,上面的stater依赖中已封装这两个依赖。