Fork me on GitHub

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

发表于 | 更新于 | 分类于 | 评论数：

解决上传文件、单页面查询多服务API和完善API显示的信息功能

Swagger-logo-white.png

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

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

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

上传文件接口配置

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

单页面查询多服务API文档

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

swagger 日志

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

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

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

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

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

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

使用windows，直接进入dist目录，点击index.html运行，或者将整个dist目录放在你的服务器里，随服务器启动。
我的80端口被占用了，就是用的81，地址栏输入http://yourdomain:81/?#(注意后面的?#，一定要带上，不然页面不会有数据返回，至于为什么，还在研究中…)，界面如下
默认界面.png
注意：这里说一下，因为不同的服务可能会牵扯到跨域访问的问题，为了解决这个问题，我在每个服务添加了下面配置

1
2
3
4
5
6
7
8
9
10
11
12
13
@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页面显示的内容，看起来更加的规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@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

-------------本文结束感谢您的阅读-------------