首页 > 代码库 > spring boot集成swagger2

spring boot集成swagger2

         做java Web的后端开发已经两年多了,一般都是开发完了接口,都把接口更新到wiki文档上,然后通知前端去文档上去查阅接口的详细描述, 当时经常接口会有变动,加参数或返回值夹字段,所以维护语线上一致的文档是一件非常麻烦的事情,前一段时间同事聊天说他们公司用的swagger2,这个不需要写文档,它是自动生成文档,只要会使用它提供的几个的注解就行,于是上网找了下资料,发现它于spring boot集成也非常方便。不废话直接看了代码。

        首先,在maven项目的pom.xml加上他需要的依赖。

	        <dependency>
	 		<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.5.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.5.0</version>
		</dependency>

   然后在Application.class的同一目录,建立一个类名为Swagger2,类如下:

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .paths(PathSelectors.any())
                .build().useDefaultResponseMessages(false);
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("微信API服务").description("wechat service").termsOfServiceUrl("no terms of service")
                .version("1.0").build();
    }

}

    然后,在Swagger2类的同一级建立一个类名为WebMvcConfig类,代码如下:

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

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

}

      这是为了让 spring boot加载处理swagger的资源的。

     然后启动Application.class启动spring boot工程,直接访问http://localhost:8080/swagger-ui.html,就可以出现REST风格的api文档。

是不是很简单。

     这其中自己也出现过问题,就是我的工程中是在拦截器中做了统一的权限验证,所以它一直都没有出现错误如下:

技术分享

 

           调试发现是在token验证时把Swagger2的访问页面的url给拦截了,也花费了自己的一点时间出解决,解决思路是在拦截其中,将url进行特殊判断,

让它通过,参考代码如下:

         技术分享

            然后,重启应用,重新访问就出现了,在线的 Api文档就出现了。

    接下来就是熟悉下 swagger2的几个注解的使用,如下

           @Api:注解controller,value为@RequestMapping路径

    @ApiOperation:注解方法,value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法,默认为false

    @ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名,value为注释,defaultValue设置默认                          值,allowableValues设置范围值,required设置参数是否必须,默认为false

           @ApiModel:注解Model

          @ApiModelProperty:注解Model下的属性,当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value

          @ApiIgnore:注解类、参数、方法,注解后将不在Swagger UI中显示。

         到此借宿,是不是很简单。大家快去尝试下吧。           

 

    

spring boot集成swagger2