如何优雅的“编写”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

欢迎在我的个人博客查看

推荐阅读更多精彩内容

  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 131,448评论 19 558
  • 前言 今天我需要把之前写的接口整理成文档,老大给了意见用swagger搞,我像发现新大陆一样的兴奋,迫不及待得去“...
    冬天只爱早晨阅读 9,209评论 6 15
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 79,095评论 12 120
  • 今天晚上把索尼摄影机装上了,倒是没什么复杂的,看看接口能插进去就插,能拧上就拧,然后试了试还能卸下来,这就算成功了...
    烟神阅读 25评论 0 0
  • 文/古月言 不是谁都会在你谢幕离开过后,还一直默默站在原地。--------题记 目录 伊楚楚踩着她十厘米的红色高...
    古月言阅读 391评论 6 3