Swagger生成的REST API文檔根據需要顯示查詢參數（但我不想要）

我正在爲我的REST API生成swagger文檔。生成的文檔顯示參數爲需要。如何讓他們不需要在招搖？在實際的REST調用中，它們不是必需的（如預期的那樣）;所以問題就在文檔中。Swagger生成的REST API文檔根據需要顯示查詢參數（但我不想要）

import javax.ws.rs.*; 

@GET 
@Produces(MediaType.APPLICATION_JSON) 
public Response getBaz(
     @DefaultValue("false") @QueryParam("foo") final boolean myFoo, 
     @DefaultValue("") @QueryParam("bar") final String myBar 
) { ... }

生成swagger.json有

... "parameters":[{ ... snip "myBar":"bar","required":true}

來源

2015-12-09 k1eran

的@ApiParam註釋會做的伎倆。從揚鞭documentation：

@ApiParam的僅與JAX-RS參數註釋（@PathParam，@QueryParam，@HeaderParam，@FormParam和JAX-RS 2，@BeanParam）使用。雖然Swagger-core默認掃描這些註釋，但@ApiParam可用於在參數上添加更多詳細信息或在從代碼中讀取值時更改這些值。 [...]

根據javadoc，您可以使用required指定是否需要該參數。要使用它，請執行以下操作：

@GET 
@Produces(MediaType.APPLICATION_JSON) 
public Response method(@ApiParam(value = "foo", required = false) @QueryParam("foo") boolean foo, 
         @ApiParam(value = "bar", required = false) @QueryParam("bar") String bar) { 
    ... 
}

查看javadoc瞭解更多詳情。

來源

2015-12-09 13:02:15

謝謝。事實上，看起來它應該完全按照我的意願去做，但是在我剛纔的測試中，它沒有任何區別，即我仍然在生成的swagger.json中看到「required」：true！ – k1eran

@ k1eran你使用的是什麼版本？ [目前的穩定版本是1.5.4]（https://github.com/swagger-api/swagger-core/releases）。舊版本中出現了@ ApiParam [已報告]（https://github.com/swagger-api/swagger-core/issues/937）的問題。 –

事實證明，我的項目使用自己的自定義maven插件來生成swagger.json文件（有點類似於https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger- codegen-maven-plugin/src/main/java/io/swagger/codegen/plugin/CodeGenMojo.java），它不幸忽略了Swagger特有的註解@ApiParam，並使用不同的方法來檢測「required」：true。（我仍然不確定爲什麼我的項目採用這種方法;但是，因爲您的建議是「標準」招牌設置的正確解決方案......謝謝您，我接受您的答案。 – k1eran

Swagger生成的REST API文檔根據需要顯示查詢參數（但我不想要）

回答

相關問題