Swagger クイックスタート (springBoot は Swagger を統合します)

1. 背景

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

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

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

OpenAPI 仕様 (略して OAS) は、API 形式または API 定義を記述するために使用される言語を定義することにより、RESTful サービス開発プロセスの標準化を試みる Linux Foundation のプロジェクトです。現在のバージョンは V3.0 で、すでにリリースされています。 github 上のオープンソース。(リンク: GitHub - OAI/OpenAPI-仕様: OpenAPI 仕様リポジトリ)
Swagger は、世界最大の OpenAPI 仕様 (OAS) API 開発ツールフレームワークです。Swagger は、オンラインインターフェイスドキュメント生成ツールです。フロントエンドおよびバックエンドの開発者は、ベースで開発していますインターフェース文書に記載されています。(公式サイト: https://swagger.io/ )
Spring Boot は Swagger を統合できますが、Swaager は Controller クラスのアノテーションに基づいています。インターフェースのドキュメントを生成する、Swagger の依存関係と構成情報を追加するだけで使用できます。

3. スワッガーの役割

Rest API ドキュメントのオンライン自動生成。
機能テスト。

4. Spring Boot 統合 Swagger

準備する：

(注: 他のバージョンも使用できます。互換性がない場合は、次のバージョンを検討してください)

JDK1.8
SpringBoot2.3.4 + maven3.8.1

1. SpringBoot プロジェクトで、Swagger の依存関係をインポートします。

        <!-- Spring Boot 集成 swagger -->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.0.RELEASE</version>
        </dependency>
         <!-- swagger注解的jar包 -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
             <version>1.5.20</version>
        </dependency>

2. アノテーション @EnableSwagger2Doc を対応する起動クラスに追加して Swagger を起動します

ここに画像の説明を挿入

3. 設定ファイルの設定 Swagger (例: application.yml、bootstrap.yml など)

(注: Swagger は yml 構成ファイルを使用するため、SwaggerConfig 構成クラスを記述する必要はありません)

ここに画像の説明を挿入

構成は次のとおりです（これは一部です）。

swagger:
  title: "这里是一个title"
  description: "这里是一个description"
  base-package: com.xuecheng.content  #必需，接口包扫描路径
  enabled: true
  version: 1.0.0

該当サービスの起動後、ブラウザは
http://localhost:該当サービスのポート番号/swagger-ui.htmlにアクセスします。

ここに画像の説明を挿入

4. Swagger の一般的な注釈

@Api : このクラスの役割を説明するためにコントローラークラスで使用されます。

例：

@Api(value = "课程信息编辑接口",tags = "课程信息编辑接口")
@RestController //相当于@Controller与@ResponseBody(响应json数据)
public class CourseBaseInfoController {
    
    

    @Autowired
    CourseBaseInfoService courseBaseInfoService;


    // @RequestBody(required = false)表示可以为空，它默认为true，不允许为空
    @ApiOperation("课程查询接口")
    @PostMapping("/course/list")
    public PageResult<CourseBase> list(@ApiParam("分页参数") PageParams pageParams, @RequestBody(required = false) QueryCourseParamsDto queryCourseParamsDto){
    
    

        PageResult<CourseBase> courseBasePageResult = courseBaseInfoService.queryCourseBaseList(pageParams, queryCourseParamsDto);
        return  courseBasePageResult;
    }
}

@ApiOperation : メソッドの機能を説明するためにメソッドで使用されます。
@ApiParam : メソッドの機能を説明するためにパラメータで使用されます

のように：

    @ApiOperation("课程查询接口")
    @PostMapping("/course/list")
    public PageResult<CourseBase> list(@ApiParam("分页参数") PageParams pageParams, @RequestBody(required = false) QueryCourseParamsDto queryCourseParamsDto){
    
    

        PageResult<CourseBase> courseBasePageResult = courseBaseInfoService.queryCourseBaseList(pageParams, queryCourseParamsDto);
        return  courseBasePageResult;
    }

@ApiModel : モデルクラスに注釈を付けるためにモデルクラスで使用されます
@ApiModelProperty : メンバー変数に注釈を付けるためにメンバー変数 (プロパティ) で使用されます。

例：

@Data
@ApiModel(value="TeachplanDto", description="课程计划信息Dto")
public class TeachplanDto extends Teachplan {
    
    


    @ApiModelProperty(value = "与媒资管理的信息")
    private TeachplanMedia teachplanMedia;

    @ApiModelProperty(value = "小章节list")
    private List<TeachplanDto> teachPlanTreeNodes;
}

5. アノテーションにおける属性の説明

ここに画像の説明を挿入

6. ケースデモンストレーション:

ここに画像の説明を挿入

最初のメソッドをクリックして詳細を表示し、テストします。

ここに画像の説明を挿入

一番下にモデル情報があります

ここに画像の説明を挿入