web-dev-qa-db-ja.com

Springfox-Swagger2を使用したSwaggerUIでのリクエストヘッダーの説明のカスタマイズ

SpringBootアプリケーションでSpringfoxSwagger2バージョン2.4.0、Springfox Swagger UIバージョン2.4.0、およびSwaggerAnnotationsバージョン1.5.0を使用しています。

ここでの問題は、コントローラーのAPI用のSwagger UIを生成でき、同じことをテストできることです。しかし、リクエストヘッダーのリクエストヘッダーの説明を指定できません。同じために@RequestHeaderアノテーションを使用しています。

コントローラAPIのコードスニペットは次のとおりです。

@RequestHeader(name = "Api-Key") String apiKey

リクエストヘッダーのSwaggerUIは次のとおりです。

enter image description here

画像で強調表示されている長方形の領域は、リクエストヘッダーの説明を表しています。

現在、name属性に記載されているデータを取得して表示します。しかし、私は同じことについて別の説明をしたいと思います。つまり、「ライセンスキーの値」

@RequestHeaderアノテーションには値、defaultValue、名前、および必要な属性しかないため、Swagger UIでこれを実現するにはどうすればよいですか？どんな助けでも本当にありがたいです。

更新：独自のカスタムアノテーションなしで、箱から出してすぐに解決策を探しています

spring-bootswaggerswagger-uiswagger-2.0springfox
7
Gandhi

多分私の答えは誰かを助けるでしょう。

前述のように Dilip Krishnan in 彼の答え 微調整されたカスタムドキュメントにはio.swagger.annotations.ApiParamまたはio.swagger.annotations.ApiImplicitParamSwaggerアノテーションを使用できます。

@ApiParamは、登録されたメソッドパラメータに使用できます。

@ApiImplicitParamは、APIパラメータが明示的に登録されていない場合に使用できます。

@RestController
@RequestMapping(value = "/v1/test", produces = "application/json")
@Api(value = "/v1/test")
public class TestController {

    @ApiOperation(value = "Do Something method", tags = "Test method")
    @RequestMapping(value = "/doSomeThing", method = RequestMethod.GET)
    public Foo doSomeThing(
            @ApiParam(value = "Param1 Description", required = true)
            @RequestParam String param) {
        throw new UnsupportedOperationException("do Some Things");
    }

    @ApiOperation(value = "Do Something Another method", tags = "Test method")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "anotherParam1", value = "Another Param1 Description", paramType = "header"),
            @ApiImplicitParam(name = "anotherParam1", value = "Another Param1 Description", paramType = "header")
    })
    @RequestMapping(value = "/doSomeThingAnother", method = RequestMethod.GET)
    public Foo doSomeThingAnother(Bar bar) {
        throw new UnsupportedOperationException("do Some Thing Another");
    }


}

そして最後にあなたは次の写真を見ることができました

Swagger UI for custom method description

9
Dmytro Boichenko

TL; DRは、それを行うために独自のプラグインを構築する必要があるということです。

基本的に、この場合の説明を補強するためのすぐに使用できる注釈は_@ApiParam_だけであり、より正確には_@ApiImplicitParam_です。残念ながら、これらの注釈はどちらも説明をサポートしていません。

したがって、私の提案は次のようになります。

  1. このような独自の注釈を作成します

    @RequestHeader(name = "Api-Key") @Description("Value of license key") String apiKey

注：これに適した 春の注釈 がすでにあります。

  1. 独自の作成 ParameterBuilderPlugin
  2. 以下に示すようにプラグインを実装します
_public class Test implements ParameterBuilderPlugin {
  @Override
  public void apply(ParameterContext parameterContext) {
    ResolvedMethodParameter methodParameter =parameterContext.resolvedMethodParameter();
    Optional<Description> requestParam = methodParameter.findAnnotation(Description.class);
    if (requestParam.isPresent()) {
      parameterContext.parameterBuilder()
        .description(requestParam.get().value());
    }
  }

  @Override
  public boolean supports(DocumentationType documentationType) {
    return false;
  }
}
_
  1. 順序 適用される値を選択します Swaggerアノテーションの後 が処理されました。

また、springfoxライブラリを 最新バージョン にアップグレードしてください。

3
Dilip Krishnan

同じ問題が発生し、次の方法で問題を解決しました。

.. @RequestHeader(value = "..") @ApiParam(value = "Description") String param ..

アイデアは、生成されたSwaggerに「description」フィールドを追加することです。それはハッキーに見えるかもしれませんが、それはあなたの個人的なケースで役立つことができる迅速で簡単な解決策です。

0
Boris