詳細なSwagger構成-Swaggerのプレイ方法を教えます

記事のディレクトリ

この記事では紹介します

この記事では主に、トークンなし、部分トークン、グローバルトークン、環境制限、複数人の開発、その他のモジュールを含む、一般的に使用されるSwaggerの構成を紹介します。これらは、基本的にプロジェクトのすべての用途に適合します。

基本的な構成プロセス（トークンなし）

1.依存関係を導入する

<!--        swagger-->
    <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.構成クラスを作成します

@EnableSwagger2 構成を開く

@Configuration
@EnableSwagger2
public class MySwaggerConfig {
    
    
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 多人开发可以设置多个Docket
     * @return
     */
    @Bean
    public Docket createRestApi(Environment environment) {
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .groupName("小组管理系统")
                //false 则不能在浏览器访问，true为默认。
                .enable(true)
                .select()
                //配置扫描接口的方式，基于包去扫描
                .apis(RequestHandlerSelectors.basePackage("com.marchsoft.group.manager.system.controller"))
                //paths()过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder().title("springboot利用swagger构建api文档")
                .description("基于小组管理的学生管理员系统")
                .termsOfServiceUrl("https://XXXX/XXXXX/group-manager/tree/develop/")
                .version("1.0")
                .build();
    }
}

3.エンティティクラスを作成します

@ApiModel(value="学生DTO对象", description="返回所有S学生最基本的信息") モデルに基づいて行動し、現在のモデルを紹介します

@ApiModelProperty(value = "id") 現在のモデルの属性を紹介します

4.インターフェースを作成します

現在のインターフェースと作者の基本情報を紹介します

@ApiOperation(value = "获取某一学生的详细信息",notes = " \n author：zhangh")

現在のインターフェースのパラメーターを紹介します

@ApiImplicitParams({@ApiImplicitParam(name = "id",value = "")})

	接口一：前端传递一个id
    @ApiOperation(value = "获取某一学生的详细信息",notes = " \n author：zhangh")
    @ApiImplicitParams({
    
    
            	@ApiImplicitParam(name = "id",value = "")
    })
    @PreAuthorize("hasAuthority('super_admin')")
    @GetMapping("/{id}")
    public Result getStudent(@PathVariable("id")    Long id) {
    
    
        StudentDTO student = studentService.getStudent(id);
        return Result.success(student);
    }
    
    接口二：  用于展示使用     前端传递的是一个对象
        @PutMapping("/update")
    public Result updateStudent(@RequestBody StudentDTO studentDTO){
    
    
        return null;
    }

5.テストと使用（トークンなし）

トークンがない場合は、ここで基本機能を設定できます。

サービスを開始し、Swaggerパスにアクセスします。

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

配置token

システムでトークンを使用する場合は、間違いなくSwaggerテスト中にトークンを追加する必要があります。次に、トークンを追加する2つの方法を紹介します。

ローカルトークン

各インターフェイスにトークン情報を手動で追加する必要があります。トラブル！

原理

DocketのglobalOperationParameters（）メソッドを呼び出し、トークンの基本的な構成情報を渡します

構成と使用：

This.apiInfo（）メソッドは基本構成にあります（トークンにソースコードがないため、ここでは再度追加しません）

globalOperation()詳細

    /***
     * @Author 
     * @Description  单一配置token
     * @Data 23:38 2021/1/29
     * @param
     * @return java.util.List<springfox.documentation.service.Parameter>
     */
    private List<Parameter> globalOperation(){
    
    
        //添加head参数配置start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        //第一个token为传参的key，第二个token为swagger页面显示的值
        tokenPar.name("Authorization")
                .description("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                //token前缀
                .defaultValue("Bearer ")
                .required(false).build();
        pars.add(tokenPar.build());
        return pars;
    }

テスト使用

構成制御

転送オブジェクト

詳細を見る

グローバルトークン

ローカルトークンを設定したばかりです。使用法は満たすことができますが、面倒です。次に、グローバルトークンを設定しましょう。

原理:

Docketが提供する構成スキームと、コンテキストを構成する2つの方法を使用します。

使用手順

上記の2つのメソッドをドケットで構成し、パラメーターを渡します

2つの方法の構成情報：

    //设置基本的介绍信息
    private List<ApiKey> securitySchemes() {
    
    
        List<ApiKey> apiKeyList = new ArrayList<>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeyList;
    }
    //过滤不需要进行验证的页面
    private List<SecurityContext> securityContexts() {
    
    
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        //带有auth的页面将不用提供token即可访问。
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }
    //全局的token配置
    private List<SecurityReference> defaultAuth() {
    
    
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

テスト使用

長期使用

1.インターフェイスドキュメントは正式な環境では使用できません

システムは通常、開発環境（dev）、テスト環境（test）、および正式に起動された（pro）の3つの環境に分けられます。
インターフェイステストは開発環境とテスト環境でのみ実行でき、正式なリリース後のインターフェイステストは固く禁じられています。
Swaggerは、対応するものも提供します。開発環境とテスト環境でテストできますが、プロ環境ではテストできません。

構成方法

 //在开发或者测试服务器使用swagger，正式环境没有swagger
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);

効果

2.複数人のコラボレーションによるインターフェイスドキュメント

通常の開発では、全員が担当するモジュールが異なる場合があります。全員がSwaggerページを操作していると、かなり混乱します。現時点では、swaggerが提供するグループ化メカニズムを使用できます。

主成分分析

いわゆるグループ化は、複数のドケットオブジェクトを作成することです

構成手順

2つのドケットを作成する

テスト効果

一般的な注釈を闊歩する

参考記事

この記事を書いている時点で、私はまだ非常に知識が豊富であり、これらの大物のブログの助けに非常に感謝しています。

クレイジーゴッドはSpringBoot14：Integrated Swagger UltimateEditionを言った

https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w

SpringBoot850Springfox-Swagger2

https://www.cnblogs.com/yichunguo/p/12665857.html#1%E3%80%81swagger%E7%AE%80%E4%BB%8B