Spring Boot 2.0.0.M 7でSwagger 2を使用してRESTful APIドキュメントを構築

Spring BootでSwagger 2を使用して強力なRESTful APIドキュメントを構築
より多くの乾物

spring-bootシリーズ1のrestfull apiとマルチ環境構成

springbootシリーズ2のログ

SpringBootシリーズ3のMVCモデルエンジン

SpringBoot 2.0.0.M 7シリーズ四異常処理

springboot 2.0.0.M 7の注記と構成

springboot 2.0.0.M 7構成mvc

springboot 2.0.0.M 7のサーブレットListener Filter

springboot 2.0.0.M 7のドメイン間

springboot 2.0.0.M 7の使用mysql

spring boot 2.0.0.M 7のデータベース-トランザクション

springboot 2.0.0.M 7のh 2埋め込みデータベースの使用

springboot 2.0.0.M 7のデータベース-redis

Spring Boot 2.0.0.M 7でSwagger 2を使用してRESTful APIドキュメントを構築する

Spring Boot 2.0.0.M 7 springBoot-mongodb

を使用

Spring Boot 2.0.0.M 7 Caching-EhCache

を使用

Spring Boot spring boot Caching-Redis

を使用

Spring Boot 2.0.0.M 7非同期メッセージサービス-AMQP(RabbitMQ)

を使用

Spring Boot 2.0.0.M 7コールRESTサービス-プロキシ

の使用方法

Spring Boot 2.0.0.M 7送信メール-テンプレートメールを使用してマルチアカウントポーリング送信

を実現

Spring Boot 2.0.0.M 7 Spring Sessionを使用してクラスタ-redis

を実現

Spring Boot 2.0.0.M 7リモートデバッグ

Spring Boot生産準備-HTTPに基づく監視

Spring Boot統合Druid

springboot思考ガイド

Spring Bootは、迅速な開発や導入が容易であるため、Spring Bootのユーザーの多くがRESTful APIの構築に使用されると信じています.RESTful APIを構築する目的は、通常、複数の最下位のビジネスロジックを共有するマルチ端末のためであるため、複数のモバイル端末またはWebフロントエンドに同時にサービスを提供する層を抽象化します.
に質問
これにより、我々のRESTful APIは、IOS開発、Android開発、Web開発など、複数の開発者または複数の開発チームに直面する可能性があります.通常、他のチームとの頻繁なコミュニケーションコストを削減するために、従来の方法では、すべてのインタフェースの詳細を記録するRESTful APIドキュメントを作成していますが、このような方法には次のような問題があります.

インタフェースが多く、細部が複雑(異なるHTTPリクエストタイプ、HTTPヘッダ情報、HTTPリクエスト内容などを考慮する必要がある)ため、このドキュメントを高品質に作成すること自体が非常に骨が折れることで、下流の苦情が絶えない.

時間が経つにつれて、インタフェースの実装を絶えず修正するときは、インタフェースドキュメントを同期的に修正しなければならないが、ドキュメントとコードは2つの異なるメディアにあり、厳格な管理メカニズムがない限り、不一致現象

を招きやすい.

Swagger 2は、Spring Bootに簡単に統合でき、Spring MVCプログラムと協力して強力なRESTful APIドキュメントを組織します.ドキュメントの作成作業量を削減し、説明内容を実装コードに統合し、ドキュメントのメンテナンスと修正コードを統合し、コードロジックを修正しながらドキュメントの説明を簡単に変更できます.また、Swagger 2は、各RESTful APIをデバッグする強力なページテスト機能も提供しています.

Swagger 2の構築
Swagger 2依存を追加

		<springfox-swagger2.version>2.2.2springfox-swagger2.version>
		
		<dependency>
			<groupId>io.springfoxgroupId>
			<artifactId>springfox-swagger2artifactId>
			<version>${springfox-swagger2.version}version>
		dependency>
		<dependency>
			<groupId>io.springfoxgroupId>
			<artifactId>springfox-swagger-uiartifactId>
			<version>${springfox-swagger2.version}version>
		dependency>

Swagger 2構成クラスの作成
Application.javaクラスでSwagger 2のコンフィギュレーションクラスSwagger 2を作成します.

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cto.edu"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("        RESTful APIs")
                .description("   http://111.231.142.109/")
                .termsOfServiceUrl("http://localhost:8081/")
                .contact("ctoDev")
                .version("1.0")
                .build();
    }

}

ドキュメントの内容の追加
@ApiOperation注記でAPIに説明を追加し、@ApiImplicitParams、@ApiImplicitParam注記でパラメータに説明を追加

@RestController
@RequestMapping("/api/blog/topic")
public class BlogTopicController {

    private static final Logger LOG = LoggerFactory.getLogger(BlogTopicController.class);

    @Resource
    private BlogTopicFacade blogTopicFacade;

    @ApiOperation(value = "        ", notes = "              ")
    @ApiImplicitParam(name = "obj", value = "{\"categoryIds\":[],\"number\":0,\"size\":1}", required = true, dataType = "JSONObject")
    @SuppressWarnings("unchecked")
    @PostMapping(value = "/findForPage")
    public ViewerResult findForPage(@RequestBody JSONObject obj) {

        ViewerResult result = new ViewerResult();
        try {
            List<String> categoryIds = (List<String>) obj.get("categoryIds");
            int number = obj.getInteger("number");
            int size = obj.getInteger("size");
            Pageable page = PageRequest.of(number, size);
            Searchable searchable = Searchable.newSearchable();
            searchable.setPage(page);

            if (categoryIds == null || categoryIds.isEmpty()) {
                Page<BlogTopic> topicPage = blogTopicFacade.listPage(searchable);
                result.setData(topicPage);
            } else {
                Page<BlogTopic> topicList = blogTopicFacade.findTopicByCategoryIds(categoryIds, page);
                result.setData(topicList);
            }

            result.setSuccess(true);
        } catch (Exception e) {
            result.setSuccess(false);
            result.setErrMessage("      ");
            LOG.error(e.getMessage(), e);
        }
        return result;
    }

    @ApiOperation(value = "      ", notes = "  Id      ")
    @ApiImplicitParam(name = "obj", value = "{\"id\":\"1\"}", required = true, dataType = "JSONObject")
    @PostMapping(value = "/findById")
    public ViewerResult findById(@RequestBody JSONObject obj) {
        ViewerResult result = new ViewerResult();
        BlogTopic topic = null;
        try {
            String id = obj.getString("id");
            topic = blogTopicFacade.getById(id);
            result.setSuccess(true);
            result.setData(topic);
        } catch (Exception e) {
            result.setSuccess(false);
            result.setErrMessage(e.getMessage());
            LOG.error(e.getMessage(), e);
        }
        return result;
    }

}

API詳細
さようはんい
API
使用場所
オブジェクトのプロパティ
@ApiModelProperty
出入りパラメータオブジェクトのフィールドに使用
プロトコルセットの説明
@Api
コントロールクラスでの使用
プロトコルの説明
@ApiOperation
コントロールの方法で
Responseセット
@ApiResponses
コントロールの方法で
Response
@ApiResponse
@ApiResponsesで使用
非オブジェクトパラメータセット
@ApiImplicitParams
コントロールの方法で
非オブジェクトパラメータの説明
@ApiImplicitParam
@ApiImplicitParamsの方法で
戻りオブジェクトの意味を説明
@ApiModel
戻りオブジェクトクラスで使用
@ApiImplicitParam

paramTypeクエリーパラメータタイプ

dataTypeパラメータのデータ型はフラグとしてのみ説明され、

は実際に検証されていない.

name受信パラメータ名

value受信パラメータの意味説明

requiredパラメータが

を入力する必要があるかどうか

defaultValueデフォルト

paramType例の詳細
queryパラメータと直接自動マッピング付与を完了

    @GetMapping(value = "/sayParam")
    @ApiOperation(value = "    ", notes = "      ")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "info", value = "    ", dataType = "String")
    })
    
    @RequestParam(value = "info", required = false, defaultValue = "        ") String myInfo

pathはアドレス形式でデータをコミットする

@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@PathVariable(name = "id") Long id

bodyはフロー形式で提出しPOSTのみをサポートする

  @ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "    ", required = true) })
  @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)
  @RequestBody MessageParam param
             json，               ，                  ，                  （ @RequestBody        ）

ヘッダーパラメータはrequest headersに提出されます

@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "  id", required = true) }) 

    String idstr = request.getHeader("id");
    if (StringUtils.isNumeric(idstr)) {
        id = Long.parseLong(idstr);
    }

Formフォーム形式で提出POSTのみサポート

@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "  id", required = true) })
 @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)

アクセス
Spring Bootプログラムを起動し、アクセス:http://localhost:8081/swagger-ui.html