springboot 集成 swagger2

springboot 集成 swagger2，配置類

具體步驟：
1，引入 jar 包

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2，編寫 configuration 類

package com.xxx.common.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置
 * eg: http://localhost:8090/swagger-ui.html
 * @date 2018/5/3 10:52
 * @since
 * @param
 */
@Configuration
// @ConditionalOnProperty(prefix = "swagger", value = { "enable" }, havingValue = "true")  // 是否啓用該 config
// @Profile{"dev, local"}
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  // 基本信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.test.controller"))  // 指定掃描的包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx系統-xxx服務 RESTful APIs")
                .description("xxx服務後臺api接口文檔")
                .contact(new Contact("xxx", null, "[email protected]"))
                .version("1.0")
                .build();
    }
}

3，常用的註解介紹與使用

3.1，swagger通過註解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。

@Api()  用於類；表示標識這個類是swagger的資源 
	tags–表示說明 
	value–也是說明，可以使用tags替代 
@ApiOperation() 用於方法；表示一個http請求的操作 
	value用於方法描述 
	notes用於提示內容 
	tags可以重新分組（視情況而用） 
@ApiParam() 用於方法，參數，字段說明；表示對參數的添加元數據（說明或是否必填等） 
	name–參數名 
	value–參數說明 
	required–是否必填
@ApiIgnore()用於類或者方法上，可以不被swagger顯示在頁面上 
	示例：
		@Api(value="用戶controller",tags={"用戶操作接口"})
		@RestController
		public class UserController {
		     @ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點")
		     @GetMapping("/getUserInfo")
		     public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {
		     // userService可忽略，是業務邏輯
		      User user = userService.getUserInfo();
		
		      return user;
		  }
		  @ApiIgnore//使用該註解忽略這個API
          @RequestMapping(value = "/hi", method = RequestMethod.GET)
          public String  jsonTest() {
               return " hi you!";
          }
		}
@ApiModel()用於類 ；表示對類進行說明，用於參數用實體類接收 
	value–表示對象名 
	description–描述 
	都可省略 
@ApiModelProperty()用於方法，字段； 表示對model屬性的說明或者數據操作更改 
	value–字段說明 
	name–重寫屬性名字 
	dataType–重寫屬性類型 
	required–是否必填 
	example–舉例說明 
	hidden–隱藏
	   示例：
			@ApiModel(value="user對象",description="用戶對象user")
			public class User implements Serializable{
			    private static final long serialVersionUID = 1L;
			     @ApiModelProperty(value="用戶名",name="username",example="xingguo")
			     private String username;
			     @ApiModelProperty(value="狀態",name="state",required=true)
			      private Integer state;
			      private String password;
			      private String nickName;
			      private Integer isDeleted;
			
			      @ApiModelProperty(value="id數組",hidden=true)
			      private String[] ids;
			      private List<String> idList;
			     //省略get/set
			}

			  @ApiOperation("更改用戶信息")
			  @PostMapping("/updateUserInfo")
			  public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){
			
			     int num = userService.updateUserInfo(user);
			     return num;
			  }
@ApiImplicitParam() 用於方法 
	表示單獨的請求參數 
@ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam 
	name–參數ming 
	value–參數說明 
	dataType–數據類型 
	paramType–參數類型 
	  示例：
		@ApiOperation("查詢測試")
	    @GetMapping("select")
	   //@ApiImplicitParam(name="name",value="用戶名",dataType="String", paramType = "query")
	    @ApiImplicitParams({
	    @ApiImplicitParam(name="name",value="用戶名",dataType="string", paramType = "query",example="xingguo"),
	    @ApiImplicitParam(name="id",value="用戶id",dataType="long", paramType = "query")})
	    public void select(){		
	    }

4，訪問 swagger2 的 UI 界面

4.1，默認的 UI 界面訪問地址

swagger2 的 UI 地址默認使用 http://youIp:port/swagger-ui.html 來訪問

4.2，自定義 swagger2 UI 訪問地址

如想要自定義訪問路徑，按照此博客步驟操作即可：https://blog.csdn.net/u012954706/article/details/81086244

如下圖所示：

5，安全起見，生產環境應當關閉swagger文檔
可以通過以下兩種方式進行關閉：

5.1，使用 @ConditionalOnProperty 註解

1. 在 swagger 的配置類上增加 @ConditionalOnProperty(prefix = "swagger", value = { "enable" }, havingValue = "true")  註解
2. 在 application.yml 或者 application.properties 文件中增加如下配置
	swagger.enable=false  # 關閉
    swagger.enable=true   # 開啓

5.2，使用 @Profile 註解

1. 在 swagger 配置類上增加 @Profile{"dev, local"} 註解，註解中指定的是開啓 swagger2 UI 界面的環境，這裏指定的是本地和開發環境
2. 配置多套環境的 application.properties 文件，在主配置文件中指定使用的環境
    spring.profiles.active=local  
   # spring.profiles.active=prod

關閉時展示的頁面，如下圖所示：