swagger2日常使用

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依赖中已封装这两个依赖。