纸上得来终觉浅,绝知此事要躬行

“交流、互助、提升”

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

欢迎在我的个人博客查看

阅读更多
版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/qqHJQS/article/details/71194917
文章标签: api 文档 测试
个人分类: JAVA api Swagger spring
所属专栏: JavaEE
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页

不良信息举报

如何优雅的“编写”api接口文档(续)

最多只允许输入30个字

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭