春ブーツ：春のDoc文書生成OpenAPI3.0

1.概要

ただ、最近のプロジェクトのドキュメントを仕上げで、会社、および文書はのためのREST APIを構築するために不可欠です。この記事では、私が説明しますSpring Docに基づいて、OpenAPI 3仕様の簡素化Spring Boot 1.xと2.xAPIドキュメント生成アプリケーションとツールのメンテナンス。

2.設定springdoc、OpenAPIを

あなたがしたい場合springdoc-OpenAPIの私たちのAPI OpenAPIの3文書の生成標準を、単に追加springdoc-OpenAPIのコアをに依存のpom.xml：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-core</artifactId>
    <version>1.1.45</version>
</dependency>

添加が完了した後、デフォルトのパスにアクセスすることができ、アプリケーションを起動し/v3/api-docs、次のようにドキュメントを表示します：

http://localhost:8080/v3/api-docs/

あなたがパスをカスタマイズしたい場合は、缶application.propertiesは、ファイルを指定しました：

springdoc.api-docs.path=/api-docs

このように、文書のアクセスパスは次のようになります。

http://localhost:8080/api-docs/

openapi3

OpenAPIのは、デフォルトのJSON形式として定義されています。以下のためのYAMLフォーマットは、次のパスへのアクセスを得ることができます。

http://localhost:8080/api-docs.yaml

3.統合springdoc-OpenAPIのと闊歩UI

独自の生成に加えてOpenAPI 3規範を、私たちもできるspringdoc-openapiとSwagger UIあなたが私たちのAPI仕様とテストのエンドポイントと対話できるように、統合されています。

3.1。Mavenは依存しています

統合するspringdoc-openapiとSwagger UI行うための唯一のものは追加されspringdoc-openapi-uiたプロジェクトのpom.xmlファイルに依存します。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.45</version>
</dependency>

アクセス闊歩-UIページ：

http://localhost:8080/swagger-ui.html

もちろんすることができます上記のように、カスタムのアクセス・パス：

springdoc.swagger-ui.path=/swagger-ui-custom.html

3.2。栗のために

仮定（Orangemanの悲しいが、そのボールああが必要!!）ボールがあるコントローラ。

@RestController
@RequestMapping("/api/ball")
public class BallController {
 
    @Autowired
    private BallRepository repository;
 
    @GetMapping("/{id}")
    public Ball findById(@PathVariable long id) {
        return repository.findById(id)
            .orElseThrow(() -> new BallNotFoundException());
    }
 
    @GetMapping("/")
    public Collection<Book> findBooks() {
        return repository.getBooks();
    }
 
    @PutMapping("/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Book updateBook(@PathVariable("id") final String id, @RequestBody final Book book) {
        return book;
    }
}

、プロジェクトを開始し、ブラウザのアドレスにアクセスしてください。

http://localhost:8080/swagger-ui-custom.html

威張っ-UIインターフェイス：

春WebFluxと統合4. springdoc、OpenAPIを

私たちは、春WebFluxプロジェクトの依存関係を追加することができますspringdoc-openapi-webflux-uiしてspringdoc-openapiとSwagger UIの統合：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webflux-ui</artifactId>
    <version>1.1.45</version>
</dependency>

次に、ブラウザのアドレスにアクセス

http://localhost:8080/swagger-ui.html

同様に、追加することにより、springdoc.swagger-ui.pathのに設定項目をapplication.propertiesドキュメント・アクセス・パスをカスタマイズするファイル。

5. `springdoc-openapi`Mavenプラグイン

springdoc-openapiライブラリが提供springdoc-OpenAPIのは、プラグインのMavenプラグ、またはYAMLオープンAPI JSON形式の記述を生成するために使用されます。

springdoc-OpenAPIを-プラグインMavenは依存する春ブート-mavenのプラグイン。Mavenの実行OpenAPIのを統合テスト・フェーズプラグイン。

だから、どのようにpom.xml設定するには、それをプラグイン？次のコードを考えてみます。

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>2.1.8.RELEASE</version>
    <executions>
        <execution>
            <id>pre-integration-test</id>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
        <execution>
            <id>post-integration-test</id>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>0.2</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

もちろん、値がカスタムウィジェットを構成することができます。

<plugin>
    <executions>
        .........
    </executions>
    <configuration> 
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl> 
        <outputFileName>openapi.json</outputFileName> 
        <outputDir>${project.build.directory}</outputDir> 
    </configuration>
</plugin>

：私たちは、プラグインで構成されたいくつかのパラメータを詳しく見ます

apiDocsUrl -アクセスにJSON形式の文書のURL、デフォルトのパス：HTTP：// localhostを：8080 / V3 / API-ドキュメント
OUTPUTFILENAME -デフォルトで定義されたパスを格納します。openapi.json
outputDirの -文書記憶の絶対パス-デフォルトは：$ {} project.build.directory

ドキュメントの自動生成6. JSR-303豆の検証

我々のようなモデルでJSR-303ビーン検証アノテーション、使用するとき@NotNull、@NotBlank、@size、@Min、@maxなど、springdoc-OpenAPIのは、これらのBeanの対応する制約を生成します。

栗の場合：

public class Ball {
 
    private long id;
 
    @NotBlank
    @Size(min = 0, max = 20)
    private String title;
 
    @NotBlank
    @Size(min = 0, max = 30)
    private String author;
 
}

ボールより豊富な文書の豆生成コンテンツ：
スキーマ

7. @ControllerAdviceとドキュメントを生成@ResponseStatus

で@RestControllerAdvice方法で使用されるクラス、注釈付き@ResponseStatus返されるステータスコードを使用して自動的に生成された文書を。@ControllerAdvice注釈付きクラス、@ResponseStatusは、 2つのメソッドを変更しました：

@RestControllerAdvice
public class GlobalControllerExceptionHandler {
 
    @ExceptionHandler(ConversionFailedException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity<String> handleConnversion(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }
     
    @ExceptionHandler(BallNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity<String> handleBallNotFound(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

文書は400と404のステータスコードを返すには今は見ることができます。
見つかりません

8.まとめ

本明細書で使用されるそれは、2.1.xのを使用するときに使用するのが最適ですので、春ブート2.2.xのバージョンでは、春ブーツバージョン2.1.8.RELEASEを電流に対応しない場合があります。

上記のコードは、私のgithubの中に見つけることができますON GitHubの上。

いいえ国民の関心ん：給付を受け取るために、物品666の再翻訳：