Добавьте параметр заголовка в документацию Swagger UI с помощью Springfox

Я хочу добавить поле параметра заголовка в автоматически сгенерированную документацию 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. Я просто хочу добавить первый тип заголовок.


spring swagger-ui springfox
person Julien    schedule 25.11.2016    source источник

Ответы (3)


arrow_upward
30
arrow_downward

Я предпочитаю использовать @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<*>{}

Если всем или большинству ваших конечных точек нужен заголовок, я лучше настрою его, как показано здесь

Если вам нужно объявить несколько параметров заголовка, вам нужно использовать аннотацию @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<*>{}
person Enoobong    schedule 27.11.2018

arrow_upward
15
arrow_downward

Я только что добавил @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 + Header Параметры

person Julien    schedule 25.11.2016

arrow_upward
5
arrow_downward

Если у вас больше параметров заголовка, то в каждом 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;
   }

 }

Ваш API будет выглядеть так, как показано ниже, с @RequestAttribute ("headerName")

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, потому что это внутреннее для приложения. чванство не требует, чтобы показать, что

@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);

   }
person sujith kasthoori    schedule 26.04.2018