java集成swagger

時間 2019-11-07

標籤 java 集成 swagger 欄目 Java 简体版

原文原文鏈接

概覽：html

java集成Swagger
Swagger-UI的使用
Springboot跨域請求的訪問解決

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。本文主要介紹了在 Spring Boot 添加 Swagger 支持，生成可自動維護的 API 文檔。java

1 . POM文件概覽：git

<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.javagithub

@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 接口項。web

配置好swagger後，在項目中訪問 ip:prot/v2/api-docs 便可訪問生成文檔的json結構，如（http://localhost:8080/v2/api-docs）能夠看到，會出現一大串Json字符串。spring

具體可參考Swagger官方示例。json

3 . Swagger-UI配置api

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;
  }

便可。

備忘：