swagger使用总结

项目中你可能已经使用到了swagger，或许你并无对它过于留意，好比说springfox、swagger-springmvc、swagger-ui他们之间的关系是什么，springfox原理是什么。

先看一个pull下来就能启动的spring-boot，swagger-ui集成demo

git项目地址 github.com/moxingwang/…

• 获取代码

git pull https://github.com/moxingwang/swagger.git
复制代码

• 启动

cd swagger
mvn spring-boot:run
复制代码

• 访问

http://localhost:8080/sw/swagger-ui.html

自此一个很是方便又简单的swagger-ui集成好了，写完业务逻辑代码能够立马公布restful api给前端调用。

具体使用

• 基于springfox使用swagger很是简单，只须要maven依赖以及少许config配置就能够实现，上面的demo中都有体现，或者直接访问springfox的github上面的demospringfox/springfox-demos 。
• springfox更详细配置请参考官方文档Springfox Reference Documentation。
• swagger annotation具体使用 Swagger-Core Annotations，这里面有详细的annotation描述。

特别注意事项

虽说swagger是个好东西，可是使用中切不能够忽略的一个问题--【安全】。dev uat1环境中你能够开放swagger给前端或者测试，千万不要把它开放给了生产，若是你的swagger ui不当心放到了生产，那是一件多么可怕的事情，真能够来个‘一锅端’，切记切记。官网文档有相关的安全配置springfox.github.io/springfox/d…。也能够在不一样环境配置中添加要给变量来控制，swagger ui是否可用(github.com/moxingwang/…)。

@Value("${swagger.switch}")
    private boolean swaggerSwitch;

    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        if (swaggerSwitch) {
            docket.enable(true);
        } else {
            docket.enable(false);
        }

        docket.apiInfo(apiInfo()).select().paths(PathSelectors.any()).build();

        return docket;
    }
复制代码

其余

如若你在spring-boot中使用swagger还嫌麻烦，想要直接一个注解搞定，建议你看SpringForAll/spring-boot-starter-swagger这个项目。

搞明白swagger，springfox是什么

swagger

Swagger 是一款目前世界最流行的API管理工具，是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。文档提供了一个方法，咱们能够用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了好比 names、order 等 API 信息。你能够经过一个文本编辑器来编辑 Swagger 文件，或者你也能够从你的代码注释中自动生成。各类工具均可以使用 Swagger 文件来生成互动的 API 文档。你须要具体阅读这里What Is Swagger?来理解。

Swagger拥有众多不一样语言和平台的开源实现与工具，他有不少实现方式，很是方便，而且支持语言特别多，详细请查看（必定要看一眼，就知道他有多强大）Tools and Integrations。

这里也能够参考Swagger Annotation 详解（建议收藏）这篇文章查看相关几个组件的中文介绍。

springfox

springfox是java对swagger的一个具体实现。springfox的前身是swagger-springmvc，用于springmvc与swagger的整合。它内部会自动解析Spring容器中Controller暴露出的接口，而且也提供了一个界面用于展现或调用这些API。

要分分钟了解springfox的原理，请参考阿里云社区API管理工具Swagger介绍及Springfox原理分析这篇文章。

最后再来看一篇文章Swagger 和 Springfox-Swagger 的关系，加深你对Swagger和Springfox-Swagger的理解。

总结

• 若是你后台开发，提供restful接口给前端。建议你使用swagger-ui提供restful的接口文档描述。
• 若是你是接口设计者，建议你使用Swagger Editor设计。
• 若是你是接口调用方，想快速生成接口调用代码，很简单，你只须要使用Swagger Editor生存client代码就好了，十分方便。

参考

• @ApiResponses and @ApiResponses in swagger
• Swagger 和 Springfox-Swagger 的关系
• [译]5.41 Swagger tutorial
• API管理工具Swagger介绍及Springfox原理分析
• Swagger Annotation 详解（建议收藏）
• SpringForAll/spring-boot-starter-swagger