spring boot集成swagger2

Posted 2020-09-21 xjz1842

         做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中显示。

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