spring boot ＋Swagger-ui 自動生成API文檔

一、spingboot整合swagger-ui
1、導包：

      <dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-bean-validators</artifactId>
			<version>2.9.2</version>
		</dependency>

2、添加SwaggerConfig類：

@Profile("local") 
@Configuration
@EnableSwagger2
public class SwaggerConfig {

/*通過此屬性，在springboot的配置文件中控制api文檔是否可用*/
    @Value("${debug}")
    private boolean debug;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.test"))
                .paths(PathSelectors.any())
                .build()
                .enable(debug);
    }
}

上述的basePackage中填寫需要生成api文檔的文件夾。

二、使用
直接以註解的形式使用，具體用法如下：

• @Api()用於類；
  表示標識這個類是swagger的資源，一般用在controller類上；
  常用的屬性有：
  tags–表示說明，可用於標註該接口類的作用
  value–也是說明，可以使用tags替代
  description-描述，可以是長文本，但從1.5.X版本之後就已廢棄
• @ApiOperation()用於方法；
  表示一個http請求的操作，一般用在controller類中的方法上；
  常用屬性有：
  value用於方法描述
  notes用於提示內容
  tags可以重新分組（視情況而用）
• @ApiParam()用於方法，參數，字段說明；
  表示對參數的添加元數據（說明或是否必填等），一般用在controller類中接收請求的參數前；
  常用屬性有：
  name–參數名
  value–參數說明，默認可省略value，直接寫參數說明
  required–是否必填，true爲必填
• @ApiModel()用於實體類
  表示對類進行說明，用於參數用實體類接收；
  常用屬性有：
  value–表示對象名
  description–描述
• @ApiModelProperty()用於實體類中的方法，字段
  表示對model屬性的說明或者數據操作更改；
  常用屬性有：
  value–字段說明
  name–重寫屬性名字
  dataType–重寫屬性類型
  required–是否必填
  example–舉例說明
  hidden–隱藏
  三、注意事項
  此處劃重點，由於是剛接觸swagger-ui，所以在使用時，有很多沒有注意到的地方，因此，無意中踩了一個坑。
  在使用@ApiModel註解時，由於沒弄清楚其屬性的具體作用，直接在Test1實體類上寫了@ApiModel（“測試類”），並且此時，給Test2實體類也如此定義：@ApiModel（“測試類”）。導致在接口文檔中查看時，發現這兩個類的屬性同時出現在了同一個Model中。
  本應當是兩個Model，而合併爲了一個Model，爲此，筆者還花費了好大一會才弄明白，本來以爲是swagger-ui出Bug了。哈哈哈。。。
  後來經過分析，發現@ApiModel註解與其他幾個註解不同，當不寫屬性時，默認爲value=“測試類”，而此註解中的value屬性，是指該實體類的對象名。其他註解的velue屬性才爲類的說明。
  當兩個類的對象名填寫爲一樣時，swagger-ui認爲這兩個類是同一個類，於是兩個類的屬性進行了合併，就出現了筆者遇到的烏龍。
  對於@ApiModel，正確的使用方法應該爲**@ApiModel(description = “測試類”)**，此時，即使兩個類中填寫了一樣的說明，也不會出現上述類屬性被合併的情形。