java集成swagger

最新推荐文章于 2025-06-09 01:33:30 发布

weixin_30906185

最新推荐文章于 2025-06-09 01:33:30 发布

阅读量171

点赞数

CC 4.0 BY-SA版权

文章标签： json java

原文链接：http://www.cnblogs.com/esileme/p/7704063.html

本文介绍如何在SpringBoot项目中集成Swagger生成API文档，包括配置Swagger2、使用Swagger-UI展示接口文档，以及解决跨域请求问题。

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

概览：

java集成Swagger
Swagger-UI的使用
Springboot跨域请求的访问解决

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。本文主要介绍了在 Spring Boot 添加 Swagger 支持，生成可自动维护的 API 文档。

1 . POM文件概览：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.8.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>

    <!--freemaker支持-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-freemarker</artifactId>
    </dependency>

    <!--添加swagger支持-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
    </dependency>

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.13</version>
    </dependency>
</dependencies>

2 . 在Application同目录下创建Swagger2的配置文件 Swagger2.java

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket config() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yl.swagger.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("这个标题")
                .contact(new Contact("yl", "47.95.196.183/esileme", "280885685@qq.com"))
                .build();
    }
}

.apis(RequestHandlerSelectors.basePackage("com.pxx.xxx.controller")) 指定了 Swagger 的扫描包名，假如不指定此项，在 Spring Boot 项目中，会生成 base-err-controller 的 api 接口项。

配置好swagger后，在项目中访问 ip:prot/v2/api-docs 即可访问生成文档的json结构，如（http://localhost:8080/v2/api-docs）可以看到，会出现一大串Json字符串。

具体可参考Swagger官方示例。

3 . Swagger-UI配置

Swagger扫描解析得到的是一个json文档，对于用户不太友好。下面介绍swagger-ui，它能够友好的展示解析得到的接口说明内容。

从github 上获取其所有的 dist 目录下东西放到需要集成的项目里，本文放入 resource/static/swagger 目录下。

修改swagger/index.html文件，默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON，这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根据自身情况填写，其实也就是步骤二中的json地址，我的是http://localhost:8080/v2/api-docs。

因为swagger-ui项目都是静态资源，restful形式的拦截方法会将静态资源进行拦截处理，所以要对springboot进行静态资源拦截的处理。

下一步，在代码中调用dist目录下的index.html文件，即可访问到接口文档说明了。

4 . springboot添加freemaker模板引擎

在默认的templates文件夹中新建welcome.ftl 内容如下:

        <!DOCTYPE html>
        <html>
            <body>
                Hello,${name}.欢迎阅读《${bookTitle}》
            </body>
        </html>

创建一个controller hellocontroller

    @Controller
    @RequestMapping("/test")
    public class HelloController {
    
    
        @RequestMapping("")
        public Object test(ModelMap map) {
    
            System.err.println("cnm");
    
            map.put("name", "yl");
            map.put("bookTitle", "bookTitle");
    
            return "welcome";
        }
    }

打开浏览器，访问http://localhost:8080/test 即可访问welcome页面。

在访问index.html的时候，会提示跨域请求没有权限的问题，在Application中添加

  @Bean
  public CorsFilter corsFilter() {
  UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
  source.registerCorsConfiguration("/**", buildConfig());
  return new CorsFilter(source);
  }

  private CorsConfiguration buildConfig() {
  CorsConfiguration corsConfiguration = new CorsConfiguration();
  corsConfiguration.addAllowedOrigin("*");
  corsConfiguration.addAllowedHeader("*");
  corsConfiguration.addAllowedMethod("*");
  return corsConfiguration;
  }

即可。

备忘：