web-dev-qa-db-ja.com

SpringfoxでSwagger UIドキュメントにヘッダーパラメーターを追加する

残りのサービスの自動生成されたswagger uiドキュメントにヘッダーパラメーターフィールドを追加したいと思います。私はSpringとSpringfoxを使用しています。

public ResponseEntity<User> saveNewUser(
        @ApiParam(value = "the user to create", required = true) @RequestBody User user) throws RestServiceException {

    userService.save(user);
    return new ResponseEntity<User>(user, HttpStatus.OK);
}

ご覧のとおり、すでにbodyタイプのパラメーターがあります。 header type oneを追加したいだけです。

springswagger-uispringfox
7
Julien

@RequestHeader(value="myHeader") String headerStrを追加しました：

public ResponseEntity<User> saveNewUser(
        @RequestHeader(value="myHeader") String headerStr,
        @ApiParam(value = "the user to create", required = true) @RequestBody User user) throws RestServiceException {

    userService.save(user);
    return new ResponseEntity<User>(user, HttpStatus.OK);
}

（import org.springframework.web.bind.annotation.RequestHeader;）

ここで説明されているソリューションを使用して、ドキュメント内のすべてのサービスにグローバルヘッダーを追加することもできます。 Spring + Springfox +ヘッダーパラメーター

11
Julien

@ApiImplicitParam私の後@RequestMappingではなく関数のパラメータとして使用します。これは、一般に、ヘッダーをフィルタ（認証など）で処理する可能性があり、そのメソッドで値を必要としないためです。

さらに、メソッドでそれらが必要な場合、Swagger autoは@HeaderParam

このスタイルは、一部の呼び出しにヘッダーが必要で、他の必要がない場合の可読性と柔軟性を向上させます。

例

@PostMapping
@ApiImplicitParam(name = "Authorization", value = "Access Token", required = true, allowEmptyValue = false, paramType = "header", dataTypeClass = String::class, example = "Bearer access_token")
fun addJob(jobRequest: Job): ResponseEntity<*>{}

エンドポイントのすべてまたはほとんどにヘッダーが必要な場合は、見たとおりに構成します here

複数のヘッダーパラメータを宣言する必要がある場合は、@ ApiImplicitParamsアノテーションを使用する必要があります。

@PostMapping
@ApiImplicitParams(
  @ApiImplicitParam(name = "Authorization", value = "Access Token", required = true, allowEmptyValue = false, paramType = "header", dataTypeClass = String::class, example = "Bearer access_token"),
  @ApiImplicitParam(name = "X-Custom-Header", value = "A Custom Header", required = true, allowEmptyValue = false, paramType = "header", dataTypeClass = String::class, example = "my header example")
)
fun addJob(jobRequest: Job): ResponseEntity<*>{}
13
Enoobong

より多くのヘッダーパラメータがある場合は、すべてのAPIにその数の@RequestHeaderがあります。

これを回避してAPIがシンプルに見えるようにするには、HeaderInterceptorを使用してヘッダー情報をキャプチャします。

In preHandle() ,  you need to extract the headerInfo in to a an Object and set it as RequestAttribute

  public class MyHeaderInterceptor extends HandlerInterceptorAdapter {

  @Override
  public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
        throws Exception { 

    HeaderVo headerVo = HeaderVo.createReqHeaderinput(
            request.getHeader("authorization"),
            request.getHeader("contentType"),                
            request.getHeader("myHeaderParam0"),
            request.getHeader("myHeaderParam1"), 
            request.getHeader("myHeaderParam3"),
            request.getHeader("myHeaderParam4"),
            request.getHeader("myHeaderParam5")

            );

     // You can do any validation of any headerInfo here.
     validateHeader(headerVo);

     request.setAttribute("headerName", headerVo);
     return true;
   }

 }

@RequestAttribute（ "headerName"）を使用すると、APIは次のようになります。

public @ResponseBody
ResponseEntity<MyResponse> getSomeApi(
        //Headers common for all the API's       

        @RequestAttribute("headerName") HeaderVo header ,
        @ApiParam(value = "otherAPiParam", required = true, defaultValue = "") 
        @PathVariable(value = "otherAPiParam") String otherAPiParam,
        @ApiParam(value = "otherAPiParam1", required = true, defaultValue = "") 
        @RequestParam(value = "otherAPiParam1") String otherAPiParam1,
        @ApiParam(value = "otherAPiParam2, required = true, defaultValue = "")
        @RequestParam(value = "otherAPiParam2") String otherAPiParam2
     ) throws MyExcp  {
  ....
 }

Swaggerは引き続きAPIのすべてのヘッダーを記述する必要があります。これは、パラメーターをswagger Docket、SwaggerConfigに追加できるためです。ignoredParameterTypesに注意してください。これは、アプリケーションの内部にあるため、HeaderVoを無視することに言及しました。 Swaggerはそれを示す必要はありません

@Bean
public Docket postsApi() {

    //Adding Header
    ParameterBuilder aParameterBuilder = new ParameterBuilder();
    List<Parameter> aParameters = new ArrayList<Parameter>();

    aParameters.clear();

    aParameterBuilder.name("myHeaderParam0").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    aParameters.add(aParameterBuilder.build());
    aParameterBuilder.name("myHeaderParam1").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    aParameters.add(aParameterBuilder.build());
   ....
   ....

    return new Docket(DocumentationType.SWAGGER_2).groupName("public-api")
            .apiInfo(apiInfo()).select().paths(postPaths()).build().ignoredParameterTypes(HeaderVo.class).globalOperationParameters(aParameters);

   }
4
sujith kasthoori