Swagger的使用

lamar醬發表於2019-07-20
Swagger

何為Swagger

設計是API開發的基礎。Swagger使API設計變得輕而易舉，為開發人員，架構師和產品所有者提供了易於使用的工具。——官網

1）具有準確的API模型

API設計容易出錯，在建模API時發現和糾正錯誤是非常困難和耗時的。Swagger Editor是第一個使用OpenAPI規範（OAS）設計API的編輯器，並且繼續滿足開發人員使用OAS構建API的需求。編輯器實時驗證您的設計，檢查OAS合規性，並隨時提供視覺反饋。

2）在設計時視覺化

最好的API是針對最終消費者而設計的。像Swagger編輯器和SwaggerHub這樣的Swagger工具為YAML編輯器提供了一個視覺化皮膚，供開發人員使用，並檢視API對最終消費者的外觀和行為。

3）在整個團隊中標準化設計風格

提供共享通用行為，模式和一致的RESTful介面的API將極大地簡化構建它們的人員和想要使用它們的消費者的工作。SwaggerHub配備了內建的API標準化工具，可以使您的API符合您的組織設計指南。

新增依賴

1、pom.xml：

在此新增如下依賴：

<dependency>
	<groupId>com.spring4all</groupId>
	<artifactId>spring-boot-starter-swagger</artifactId>
	<version>1.5.1.RELEASE</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.8.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.8.0</version>
</dependency>
複製程式碼

啟動類

在Spring Boot專案啟動類上新增@EnableSwagger2註解。

專案配置

在專案的.properties中新增：

#swagger開啟關閉
swagger.enabled=true
複製程式碼

類配置

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2 的配置注入
 * @author ligj
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Value("${swagger.enabled}")
    private boolean enable;
    @Bean
    public Docket createRestApi() {
		
        return new Docket(DocumentationType.SWAGGER_2).enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("你的title")
                .description("xxx 專案RestAPI文件")
                .termsOfServiceUrl("...")
                .version("1.0")
                .build();
    }

	
}
複製程式碼

攔截器

如果有設定攔截器，那麼需要放行swagger。

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(authenticationInterceptor())
         .addPathPatterns("/**")
         .excludePathPatterns("/swagger-resources/**", "/webjars/**","/v2/**", "/swagger-ui.html/**"); //放行swagger;
}
複製程式碼

如果專案中沒有攔截器，並且遇到了No mapping found for HTTP request with URI [/swagger-resources/configuration/ui] in DispatcherServlet with name 'dispatcherServlet'，那麼需要新增WebMvcConfigurerConfig：

package com.lamarsan.livelihood_background.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * className: WebMvcConfigurerConfig
 * description: TODO
 *
 * @author hasee
 * @version 1.0
 * @date 2019/8/12 10:02
 */
@Configuration
@EnableWebMvc
public class WebMvcConfigurerConfig implements WebMvcConfigurer {
    private CorsConfiguration buildConfig() {
        CorsConfiguration corsConfiguration = new CorsConfiguration();
        corsConfiguration.addAllowedOrigin("*");
        corsConfiguration.setAllowCredentials(true);
        corsConfiguration.addAllowedHeader("*");
        corsConfiguration.addAllowedMethod("*");

        return corsConfiguration;
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
}
複製程式碼

常用API

常用註解有：

1、Api

2、ApiModel

3、ApiModelProperty

4、ApiOperation

5、ApiParam

6、ApiResponse

7、ApiResponses

8、ResponseHeader

Api註解

Api用在類上，說明該類的作用，可以標記一個Controller類作為swagger文件資源，標記在類上，使用方式：

@Api(tags = "資訊")
public class Controller{
	...
}
複製程式碼

屬性配置

屬性名稱 備註
value url的路徑值
tags 如果設定這個值，value的值會被覆蓋
description 對api資源的描述
basePath 基本路徑可以不配置
position 如果配置多個Api 想改變顯示的順序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高階特性認證時配置
hidden 配置為true 將在文件中隱藏

ApiOperation註解

用在方法上，說明方法的作用，每一個url資源的定義，使用方式：

@ApiOperation(value = "your describle")
@RequestMapping(value = "/xxx",method = RequestMethod.POST, produces = "application/json;charset=UTF-8")
public RestResponseModel getSongByUnit(@RequestBody @Validated UnitDTO unitDTO, @ApiIgnore ReqUser reqUser){
    your code
}
複製程式碼

屬性配置

屬性名稱 備註
value url的路徑值
tags 如果設定這個值、value的值會被覆蓋
description 對api資源的描述
basePath 基本路徑可以不配置
position 如果配置多個Api 想改變顯示的順序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高階特性認證時配置
hidden 配置為true 將在文件中隱藏
response 返回的物件
responseContainer 這些物件是有效的 "List", "Set" or "Map".，其他無效
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code http的狀態碼 預設 200
extensions 擴充套件屬性

ApiParam註解

ApiParam為請求屬性，使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)
複製程式碼

屬性配置

屬性名稱 備註
name 屬性名稱
value 屬性值
defaultValue 預設屬性值
allowableValues 可以不配置
required 是否屬性必填
access 不過多描述
allowMultiple 預設為false
hidden 隱藏該屬性
example 舉例子

ApiModelProperty註解

描述一個model的屬性，具體用法如下：

@ApiModelProperty(value = "your describle")
private String id;
複製程式碼

swagger頁面

執行springboot專案後，在瀏覽器中輸入http://localhost:8080/swagger-ui.html#/，頁面效果如圖所示：

Swagger的使用

相關文章