Swagger-UIを使用して美しいインターフェイスドキュメントをオンラインで生成する方法

1.簡単な紹介

Swaggerは、OpenAPI（OpenAPI仕様）仕様を実装するツールセットです。OpenAPIはLinux Foundationのプロジェクトであり、API形式またはAPI定義を記述するための言語を定義することにより、RESTfulサービスの開発プロセスを標準化しようとします。

Swaggerは、フロントエンドおよびバックエンドの開発者を大幅に促進します。Swaggerを使用したことのある人なら誰でもそうです。ただし、一部の人々はSwaggerを経験しておらず、難しい手書きのインターフェイスドキュメントをまだ持っています。これは面倒で標準的ではありません。一部の人々はそれを使用したことがありますが、それだけでは薄暗いです。CVを使用するために直接使用する方法を確認してください体系的ではなく、非常に断片化されています。以前はこのように見えましたが、依存関係を追加し、プロジェクトの開始後にそれにアクセスすることを知っているだけです：localhost：8080 / swagger-ui.html、生成されたドキュメントを見ることができます。これは非常に簡単です。

生成されたドキュメントに常に基本的なエラーコントローラーが存在することを確認した後、強迫性障害が犯された場合はそれを取り除きたいので、swaggerの構成を確認してここに記録しました。

公式サイト：https : //swagger.io/

公式の指示を参照してください：

Swaggerに含まれるツールセット：

Swagger Editor： Swagger Editorを使用すると、ブラウザーでYAMLのOpenAPI仕様を編集し、リアルタイムでドキュメントをプレビューできます。
Swagger UI： Swagger UIは、OAS標準に準拠するAPIから美しいドキュメントを動的に生成できるHTML、JavaScript、CSSアセットのコレクションです。
Swagger Codegen： OpenAPI仕様に従って、APIクライアントライブラリ（SDK生成）、サーバースタブ、およびドキュメントの自動生成を可能にします。
Swagger Parser： JavaからOpenAPI定義を解析するための独立したライブラリ
Swagger Core： OpenAPI定義を作成、使用、および使用するためのJava関連ライブラリ
Swagger Inspector（無料）： APIを検証し、既存のAPIからOpenAPI定義を生成できるAPIテストツール
SwaggerHub（無料および商用）： OpenAPIを使用するチーム用に作成されたAPI設計およびドキュメント。

第二に、エントリーケース

SpringBootにはSwaggerが統合されており、swaggerのAPIドキュメントは簡単なアノテーションを使用して生成できます。

1.依存関係を導入する

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.9.2</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.9.2</version>
</dependency>

2.設定を書き込む

@Configuration
@EnableSwagger2 // Swagger的开关，表示已经启用Swagger
public class SwaggerConfig {
    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host("localhost:8081")// 不配的话，默认当前项目端口
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // 选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
//                .apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 选择监控的package
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只监控有ApiOperation注解的接口
                //不显示错误的接口地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
                .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XXXX项目接口文档")
                .contact(new Contact("Hanstrovsky", "www.hanstrovsky.com", "[email protected]"))
                .description("这是用Swagger动态生成的接口文档")
                .termsOfServiceUrl("NO terms of service")
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0")
                .build();
    }
}

3.テストを開始します

サービスを開始します：http：// localhost：8081 / swagger-ui.html

swagger-uiが提供するAPIページをご覧ください。

作成したインターフェイスを確認できます。いずれかをクリックすると、インターフェイスの詳細情報が表示されます。

以下を含む詳細なインターフェース宣言を見ることができます。

リクエスト方法：
リクエストパス
リクエストパラメーター
対応およびその他の情報

右上隅をクリックしてtry it out!、インターフェースをテストすることもできます。

3.共通の注意事項

ちょうど今のドキュメントの説明では、swagge-uiはインターフェースに応じて自動的に生成されますが、詳細は不十分です。必要に応じて、アノテーションを使用してインターフェース宣言をカスタマイズできます。一般的なメモは次のとおりです。

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

例：

@PostMapping("/people")
@ApiOperation(value = "保存人员信息")
@ApiResponses({
       @ApiResponse(code = 0, message = "保存成功"),
       @ApiResponse(code = 1, message = "保存失败")
})
public FrontResult save(
         @ApiParam(value = "保存参数", example = "")
         @RequestBody People people) {
     people.setBirthday(Timestamp.valueOf(LocalDateTime.now()));
     return new FrontResult(FrontResult.SUCCEED, "保存成功", peopleDao.save(people));
}

@Data
@ApiModel(description = "人员信息保存请求对象")
public class People {
    @ApiModelProperty(value = "人员编号")
    private Long id;
    @ApiModelProperty(value = "姓名", required = true,position = 1)
    private String name;
    @ApiModelProperty(value = "性别", required = true,position = 2)
    private String sex;
    @ApiModelProperty(value = "生日", required = true,position = 3)
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Timestamp birthday;
}

ドキュメントを見る：

4、美化

慣れていないと感じた場合は、Swagger-Bootstrap-UIを使用して、SwaggerのデフォルトUIを置き換え、左右のメニュースタイルのSwagger-UIを実装して、より明確で明確にすることができます。

1.依存関係を追加する

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2.プロジェクトを再起動します

http：// localhost：8080 / doc.htmlにアクセスします。