豊富でダイナミックな「実装上の注意事項」をスワッガーで作成できますか？

Question

私は現在、「実装の注意事項」のセクションで私のWebサービスメソッドを文書化するためにApiOperationアノテーションを使用しています：

@ApiOperation(
    value = "Searches for information", 
    notes = "This service searches for information" 
) 
public Response getInformation(...) 

私はプロパティファイルを使用するために今、私のノートを強化したい、データベースからの情報を、などIそれが豊かでダイナミックであることを望みます。

それでは、私は、データベースからの情報が含まれているPOJOを持っているとしましょう：

@Entity 
public class SortColumnField { 
    @Id 
    @Column 
    private String fieldName; 
    @Column 
    private String fieldDescription; 
} 

は、私がこのようなオブジェクトから闊歩ドキュメントを生成することができるようになるものはありますか？

Answer 1

あなたはこれを行うための2つの選択肢があります。

まず、ノートセクションは、具体的にはgithubの風味、値下げをサポートしています。そのセクションにかなり豊富な情報を含めることができ、ほとんどのツールはそれを正しくレンダリングします。

次に、Operation ObjectはexternalDocsというフィールドをサポートしています。 Swagger-UIではレンダリングされませんが、簡単にUIをフォークして複雑なドキュメントを参照することができます。複雑なドキュメントは、標準ツールでレンダリングされる構造に収まらない場合があります。