swaggerノート

38173 ワード

swaggerノート
  • 紹介
  • モジュール
  • バージョン選択
  • springfox
  • xiaoymin
  • を使用
  • 依存部
  • コード部
  • 資料文献
  • knife 4 j項目説明
  • swagger使用例
  • springfox

  • 紹介する
  • swaggerはapiを管理するためのオープンソースプロジェクト
  • である.
  • は、チームにapiドキュメントを共有し、apiインタフェースをテストするツール
  • を提供するために使用することができる.
  • ドキュメントおよびテストツールは、コードの更新に伴って
  • を更新します.
  • わずかな構成で
  • を実現できる.
    モジュール
  • swaggerはswaggerモジュールとswagger-uiモジュールの前後端分離
  • に分けられる.
    バージョンの選択
    springfox
  • 最新バージョン2.9.2
  • mapを受信または返す場合、beanオブジェクトまたはプラグイン(欠陥)によってインタフェースドキュメントに特定のパラメータと戻りフィールド
  • を含める必要がある.
  • api uiは、上下スクロール折り畳み枠パケットの形態で提供する
  • である.
  • 中国人の習慣に合わない
  • でも慣れているのか使っているうちに
  • が変わった.
  • 最も重要なのはapiテスト機能入力記憶機能なし
  • である.
  • 再びウェブページに入った後に再び同じインタフェースのパラメータをテストして機能をヒントにしていませんこれはこのようにします
  • 複数のインタフェースを同時にテストする必要があるとき、パンくずがないので、転がる海に迷う
  • .
    xiaoymin
  • コアはまだ使用されているswaggerはswagger-uiをいくつかの強力な機能を追加した
  • に交換しました.
  • は、map問題
  • を解決するための独立した注釈を提供する.
  • ui国人の習慣に合致する左右の欄
  • 入力記憶機能
  • をテストする.
  • パンくずがある同時に複数のインタフェースを要求することも便利である
  • .
  • 私のようなテストインタフェースをuiとして使う人にとっては使いやすい
  • です.
    使用
  • 分文単応用と多応用の2つのケース
  • 依存部分
  • springfox
    
    <dependency>
    	<groupId>io.springfoxgroupId>
    	<artifactId>springfox-swagger2artifactId>
    	<version>2.9.2version>
    dependency>
    
    <dependency>
    	<groupId>io.springfoxgroupId>
    	<artifactId>springfox-swagger-uiartifactId>
    	<version>2.9.2version>
    dependency>
    
  • xiaoymin
    
    <dependency>
    	<groupId>com.github.xiaoymingroupId>
    	<artifactId>knife4j-spring-boot-starterartifactId>
    	<version>2.0.2version>
    dependency>
    
     <dependency>
    	<groupId>com.github.xiaoymingroupId>
    	<artifactId>knife4j-micro-spring-boot-starterartifactId>
    dependency>
    
  • 注意事項
    org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NoSuchMethodError: com.google.common.collect.FluentIterable.append(Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable;
    at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:184) ~[spring-context-5.0.8.RELEASE.jar:5.0.8.RELEASE]
    Caused by: java.lang.NoSuchMethodError: com.google.common.collect.FluentIterable.append(Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable;
    
    タイムズ紙のエラーを実行した場合、デフォルトで導入されたキュウリのバージョンが低すぎるため、キュウリをアップグレードする方法が不足しています.
    <dependency>
    	<groupId>com.google.guavagroupId>
    	<artifactId>guavaartifactId>
    	<version>29.0-jreversion>
    dependency>
    

    上の依存を加えるのはやはりだめならば、その瓜娃子が欠片付けモードに入るため、あなたの調教の下で依存の中に衝突があるかどうかを見ることができます複数のguavaのサブバージョンを見て低バージョンの排除ideaのproject structureのmodulesの依存の下で低バージョンの瓜娃子あるいはmvnの依存分析を削除して手作業で排除することができます

  • コードセクション
  • 単一アプリケーション
  • 直接引用依存作成Docket(この名前はすごいようですね)spring管理オープンswagger
  • に渡します
    @EnableKnife4j //knife4j         
    @EnableSwagger2
    @Configuration
    @Profile({"dev","test","local","tt"})
    public class SwaggerConfig {
    
        @Bean
        @Order(value = 1)
        public Docket groupRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaominfo.swagger.service.user.controller"))
                .paths(PathSelectors.any())
                .build()
                //     Authorization Authorization-x  token  
                .securityContexts(Lists.newArrayList(securityContext(),securityContext1()))
                .securitySchemes(Lists.<SecurityScheme>newArrayList(apiKey(),apiKey1()));
        }
    
        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
                    .title("api  ")
                    .description("
    api
    "
    ) .termsOfServiceUrl("http://www.shangtian.com/") .contact("[email protected]") .version("1.0") .build(); } private ApiKey apiKey() { return new ApiKey("BearerToken", "Authorization", "header"); } private ApiKey apiKey1() { return new ApiKey("BearerToken1", "Authorization-x", "header"); } private SecurityContext securityContext() { return SecurityContext.builder() .securityReferences(defaultAuth()) .forPaths(PathSelectors.regex("/.*")) .build(); } private SecurityContext securityContext1() { return SecurityContext.builder() .securityReferences(defaultAuth1()) .forPaths(PathSelectors.regex("/.*")) .build(); } List<SecurityReference> defaultAuth() { AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; return Lists.newArrayList(new SecurityReference("BearerToken", authorizationScopes)); } List<SecurityReference> defaultAuth1() { AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; return Lists.newArrayList(new SecurityReference("BearerToken1", authorizationScopes)); } }
  • マルチアプリケーション
  • は、アプリケーションごとに単一アプリケーションに従って
  • であることができる.
  • しかし、これで20以上の工事があれば訪問するのはかなり爽やかだと思います.
  • apiドキュメントを提供するすべてのサービスはswaggerモジュール
  • を参照する.
  • は、swaggerインタフェースにアクセスするサービス参照swagger-uiモジュールを提供する必要があり、ルーティング情報を提供することは、通常、ゲートウェイサービス
  • である.
  • 他のサービスがルーティング情報を収集する必要がある場合は、ゲートウェイまたは登録センターでブロードキャスト収集を取得することができ、入力方式
  • を採用することができる.
  • ステップは、ルーティング情報に基づいてインタフェース要求アドレスを生成する->要求アドレスに基づいてターゲットサービスインタフェース
  • を要求する.
  • これにより、複数のサービスが必要なapiにアクセスする際に複数のウェブサイトを開く必要があるという問題を解決する
  • .
  • 現在5つのサービスが登録センターを除いてapiドキュメントサービスを提供する必要がある場合は、次の
  • に従います.
  • 1登録センター1 userサービス1受注サービス1商品サービス1ゲートウェイサービス
  • 登録センターはuser、注文、商品サービス導入サービス側にかかわらず、単一アプリケーションの構成に依存して
  • を歩く.
  • ゲートウェイサービス導入サービス側とui依存構成は以下の
  • である.
    @EnableSwagger2
    @Configuration
    @Profile({"dev","test","local","tt"})
    public class SwaggerConfig {
    
        @Bean
        @Order(value = 1)
        public Docket groupRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
                    .title("api  ")
                    .description("
    api
    "
    ) .termsOfServiceUrl("http://www.shangtian.com/") .contact("[email protected]") .version("1.0") .build(); } }
    @Component
    @Primary
    @Profile({"dev","test","local","tt"})
    public class SwaggerResourceConfig implements SwaggerResourcesProvider {
    
        Logger logger= LoggerFactory.getLogger(SwaggerResourceConfig.class);
    
    
        @Autowired
        RouteLocator routeLocator;
    
        @Override
        public List<SwaggerResource> get() {
            //    router
            List<SwaggerResource> resources = new ArrayList<>();
            List<Route> routes = routeLocator.getRoutes();
            logger.info("Route Size:{}",routes.size());
            for (Route route:routes) {
                resources.add(swaggerResource(route.getId(), route.getFullPath().replace("**", "v2/api-docs")));
            }
            return resources;
        }
        private SwaggerResource swaggerResource(String name, String location) {
            logger.info("name:{},location:{}",name,location);
            SwaggerResource swaggerResource = new SwaggerResource();
            swaggerResource.setName(name);
            swaggerResource.setLocation(location);
            swaggerResource.setSwaggerVersion("1.0");
            return swaggerResource;
        }
    }
    
  • 上記の構成により、user、注文、商品サービスのapiドキュメント
  • にゲートウェイでアクセスできます.
  • ゲートウェイサービスがzulでない場合、またはゲートウェイがない場合、nginxの逆エージェントを介して対応するSwaggerResourceConfigを実装すればよい
  • .

    資料文献
    knife 4 jプロジェクト説明
    swagger使用例
    springfox