如何优雅的“编写”api接口文档（续）

Swagger-logo-white.png

接着上一篇如何优雅的“编写”api接口文档

这篇续篇主要说一下以下三点

• 文件上传参数配置
• 单独部署SwaggerUI(实现在一个页面查找不同域名的API功能)
• 完善SwaggerUI的展示内容

上传文件接口配置

接着昨天的bug，有一接口需要上传文件，怎样去配置注解，才能让Swagger的页面拥有测试的功能即有文件上传的入口(不知客官有咩有明白。。。)
在网上找了半天的资料也没有找到，后来我索性直接将@ApiImplicitParams注解去掉，竟然可以了，英吹思婷~，文件这块解决。

单页面查询多服务API文档

不知道看到这个二级标题有咩有明白，上一篇是将Swagger集成在单独的服务里，但是，现在你有多个服务，难道要在地址栏输入多个地址去查看API么，总感觉怪怪的，我反复的查看服务启动的swagger日志，发现了如下图的日志

swagger 日志

然后我又看了看官网提供的Tools,好像明白了什么

Swagger 根据注解会将接口的相关信息生成一个供SwaggerUI界面使用的一个接口即/v2/api-docs

官网里的LIVE DEMO是一个在线服务，为了安全我这里不使用在线的，准备在本地自己搭一个
将SwaggerUI源代码checkout到本地

git clong https://github.com/swagger-api/swagger-ui`

如果你用的linux，进入目录并使用下面命令

docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui

使用windows，直接进入dist目录，点击index.html运行，或者将整个dist目录放在你的服务器里，随服务器启动。
我的80端口被占用了，就是用的81，地址栏输入http://yourdomain:81/?#(注意后面的?#，一定要带上，不然页面不会有数据返回，至于为什么，还在研究中...)，界面如下

默认界面.png

注意：这里说一下，因为不同的服务可能会牵扯到跨域访问的问题，为了解决这个问题，我在每个服务添加了下面配置

@Configuration  
public class CorsConfig extends WebMvcConfigurerAdapter {  

    @Override  
    public void addCorsMappings(CorsRegistry registry) {  
        registry.addMapping("/**")  
                .allowedOrigins("*")  
                .allowCredentials(true)  
                .allowedMethods("GET", "POST", "DELETE", "PUT")  
                .maxAge(3600);  
    }  

}  

如果上线了，你可以把allowedOrigins的*号换成指定的域名

好了，在界面里的输入框里输入你想查找的API文档的地址，如
http://127.0.0.1:8080/v2/api-docs
这个时候你就能看到内容啦~~~~(注意和直接在地址栏输入http://127.0.0.1:8080/swagger-ui.html#/)的区别

单独API.png

可查询API页面.png

完善界面显示内容

添加如下代码，可以自定义API页面显示的内容，看起来更加的规范

@SpringBootApplication
@EnableSwagger2
public class Application {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.quick.api")) //扫描API的包路径
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot整合Swagger2") // 标题
                .description("api接口的文档整理，支持在线测试") // 描述
                .termsOfServiceUrl("http://vector4wang.tk/") //网址
                .contact("Vector.Wang") // 作者
                .version("1.0") // 版本号
                .build();
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

结果如上面的单独API

欢迎在我的个人博客查看