swagger使用总结

最新推荐文章于 2025-03-20 13:45:32 发布

weixin_33828101

最新推荐文章于 2025-03-20 13:45:32 发布

阅读量206

点赞数

CC 4.0 BY-SA版权

文章标签：前端 ui git ViewUI

原文链接：https://juejin.im/post/5b4da9196fb9a04f9d1be6c4

本文介绍了如何使用Swagger和Springfox为RESTful API生成文档。通过一个Spring Boot项目的实例，展示了集成Swagger-ui的方法，并讨论了安全性配置的重要性。同时，提供了Springfox原理的概述，帮助开发者更好地理解和应用。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

项目中你可能已经使用到了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 详解（建议收藏）这篇文章查看相关几个组件的中文介绍。