Question

我正在为我的REST API生成swagger文档。生成的文档显示参数必需。如何让他们不需要的招摇？在实际的REST调用中，它们不是必需的（如预期的那样）;所以问题就出在文档中。

<RelativeLayout 
     xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     xmlns:ads="http://schemas.android.com/apk/res-auto">


   <!-- Framelayout to display Fragments -->

   <FrameLayout
       android:id="@+id/frame_container"
       android:layout_width="match_parent"
       android:layout_height="match_parent" />

   <!-- Listview to display slider menu -->

   <ListView
       android:id="@+id/list_slidermenu"
       android:layout_width="270dp"
       android:layout_height="match_parent"
       android:layout_gravity="start"
       android:background="@drawable/sidebar_gradient"
       android:choiceMode="singleChoice"
       android:divider="@color/white_60_per_trans"
       android:dividerHeight="0.5dp" />

   <com.google.android.gms.ads.AdView
       android:id="@+id/adView"
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:layout_centerHorizontal="true"
       android:layout_alignParentBottom="true"
       ads:adSize="BANNER"
       ads:adUnitId="@string/banner_ad_unit_id">
   </com.google.android.gms.ads.AdView>
</RelativeLayout>

生成的swagger.json有

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
) { ... }

Answer 1

@ApiParam注释可以解决问题。来自Swagger 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了解详情。

Swagger生成REST API文档，根据需要显示查询参数（但我不需要）

1 个答案: