使用Spring boot可以很快速的开发restful api，但是如果手工维护api文档就太费事了，很难做到同步。

swagger可以将代码和api文档维护在一起，通过访问服务进程的swagger页面就可以得到完善的api文档，还可以直接Try out。

swagger的使用，可以参考 程序员DD 的这篇文章：Spring Boot中使用Swagger2构建强大的RESTful API文档，快速开始，原文写的很好，我就不搬运了。总的来说，还是很方便的。

由于我的应用还配置了spring security，在与swagger配合的时候遇到了一些问题，记录一下，也许对你有用。

第一个问题是，不要在IDEA里直接Run Spring Boot Application。之前图方便，一直是这样跑的，但发现这样在加载swagger的静态资源的时候，会有下面的Not Found问题。改成 JAR Application 就正常了。

This application has no explicit mapping for /error, so you are seeing this as a fallback. 

Wed Jan 10 11:56:24 IST 2018
There was an unexpected error (type=Not Found, status=404). 
No message available"" 

但很奇怪的是，如果是demo，Run Spring Boot Application也是正常的。可能是因为我依赖了某些包的原因？

第二个问题是，我希望访问 swagger api doc 时，不需要认证。这个可以通过在spring security中配置规则来设置。由于我定义了HttpSecurity，所以没有像这里这样写在WebSecurity里。

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/v2/api-docs", "/configuration/ui", "/swagger-resources/**",
                        "/configuration/security", "/swagger-ui.html", "/webjars/**").permitAll()
            .anyRequest().authenticated()
                .and()
            .logout()
                .permitAll()
                .and()
            .formLogin()
                .permitAll()
        .and().httpBasic();

如果你在访问swagger时，遇到类似下面的错误，那么很有可能是它要访问的url不在上面代码的antMatchers里，按ant规则添加就是了。

Also, http://localhost:8080/forest/swagger-ui.html is showing 404 not found along with a message
Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually:

我在Github上放了一个工程spring-boot-swagger-security-example，供参考。

swagger的功能很强大，还可以自动生成sdk。

---