Swagger はインターフェイスドキュメントを生成します

フロントエンドとバックエンドの別々の開発では、通常、バックエンドのプログラマーがインターフェースを設計し、完成後にインターフェースの文書を作成し、最終的にフロントエンドエンジニアに文書を引き渡します。 -end エンジニアは開発用のドキュメントを指します。

インターフェイスドキュメントは、いくつかのツールを使用して迅速に生成できます。このプロジェクトでは、Swagger を使用してインターフェイスオンラインドキュメントを生成します。

スワッガーとは何ですか?

OpenAPI 仕様 (略して OAS) は、API 形式または API 定義を記述するために使用される言語を定義することにより、RESTful サービス開発プロセスの標準化を試みる Linux Foundation のプロジェクトです。現在のバージョンは V3.0 で、 github でオープンソースとしてリリースされています。

（GitHub - OAI/OpenAPI-仕様: OpenAPI 仕様リポジトリ）

Swagger は世界最大の OpenAPI 仕様 (OAS) API 開発ツールフレームワークであり、オンラインインターフェイスドキュメント生成ツールであり、フロントエンドおよびバックエンドの開発者はインターフェイスドキュメントに基づいて開発します。( API ドキュメントと Teams 用の設計ツール | Swagger )

Spring BootはSwaggerを統合することができ、SwaagerはControllerクラスのアノテーションに従ってインターフェースドキュメントを生成し、Swaggerの依存関係や設定情報を追加すれば利用可能です。

1. swagger-spring-boot-starter 依存関係を API プロジェクトに追加します

Java

<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

2. swagger のスキャンパッケージパスとその他の情報を bootstrap.yml に設定します。base-package はスキャンパッケージパスで、Controller クラスをスキャンします。

Java
swagger:
  タイトル: "Xuecheng オンラインコンテンツ管理システム"
  説明: "コンテンツシステム管理システムはコース関連情報を管理します"
  基本パッケージ: com.xuecheng.content
  有効: 真の
  バージョン: 1.0.0

3. @EnableSwagger2Doc アノテーションをスタートアップクラスに追加します。

サービスを再度開始すると、プロジェクトが起動します。http ://localhost:63040/content/swagger-ui.htmlにアクセスしてインターフェイス情報を表示します。

次の図は、Swagger インターフェイスドキュメントのインターフェイスを示しています。

この文書には 2 つの問題があります。

1. インターフェイス名は、 course-base-info-controller の名前が直感的ではないことを示しています

2. コースクエリは post メソッドであり、post /course/list のみを表示します。

以下のように変更を加え、インターフェースの説明にいくつかの注釈を追加し、RequestMapping を PostMapping に変更します。

Bash
@Api(value = "コース情報編集インターフェイス", tags = "コース情報編集インターフェイス")
@RestController
public class CourseBaseInfoController { @ApiOperation("コースクエリインターフェイス") @PostMapping("/course/list") public PageResult< CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){ //.... } }

5. サービスを再度開始し、プロジェクトを開始し、http://localhost:63040/content/swagger-ui.html にアクセスしてインターフェイス情報を表示します。

次の図は、Swagger インターフェイスドキュメントのインターフェイスを示しています。

インターフェイスドキュメントにはインターフェイスパラメータに関する説明があり、モデルクラスの属性を説明するアノテーションをモデルクラスに追加することもできるため、インターフェイスドキュメントを読むのに便利です。

たとえば、以下の赤でマークされた属性名は、swager アノテーションを通じて中国語の名前でマークできます。これは、インターフェイスドキュメントを読むのに便利です。

ラベル付けの方法は非常に簡単です。

モデルクラスを見つけて、プロパティに注釈を追加します。

Java
public class PageParams { ... @ApiModelProperty("現在のページ番号") private Long pageNo = 1L; @ApiModelProperty("ページあたりのデフォルトのレコード数") private Long pageSize = 30L; ... public class QueryCourseParamsDto { //監査ステータス@ApiModelProperty("監査ステータス") private String AuditStatus; //コース名 @ApiModelProperty("コース名") private String courseName; }

次の図に示すように、サービスを再起動し、インターフェイスドキュメントを再度入力します。

Swaager の一般的な注釈は次のとおりです。

Swagger アノテーションを Java クラスに追加すると、Swagger インターフェイスを生成できます。一般的な Swagger アノテーションは次のとおりです。

Java
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

@ApiImplicitParam属性如下：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

使用Swagger可以进行接口的测试。

修改接口内容，添加一些测试代码

Java
@ApiOperation("课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){

    CourseBase courseBase = new CourseBase();
    courseBase.setName("测试名称");
    courseBase.setCreateDate(LocalDateTime.now());
    List<CourseBase> courseBases = new ArrayList();
    courseBases.add(courseBase);
    PageResult pageResult = new PageResult<CourseBase>(courseBases,10,1,10);
    return pageResult;

}

debug方式启动，在 return 处打断点，再用swagger请求接口。

通过下图可以看到请求参数已经正常请求至controller方法

放行继续运行，观察swagger界面，结果可以正常返回

不过存在一个问题就是LocalDateTime类型的数据转json后数据格式并不是我们要的年月日时分秒。

json への変換時に文字列と LocalDateTime 型の間の変換を実現するには、基本プロジェクトの com.xuecheng.base.config パッケージの下に LocalDateTimeConfig クラスを構成します。

Swagger はインターフェイス ドキュメントを生成します

おすすめ

Swagger はインターフェイスドキュメントを生成します