SpringBoot integrierte Swagger-Beispielanalyse

1. Übersicht über Schnittstellendokumente

swagger ist ein beliebtes Echtzeit-Tool zur Generierung von Schnittstellendokumenten. Schnittstellendokumente sind in aktuellen Front-End- und Back-End-Trennungsprojekten ein unverzichtbares Werkzeug. Vor der Front-End- und Front-End-Entwicklung muss das Back-End zunächst das Schnittstellendokument erstellen Nachdem die Entwicklung beider Parteien abgeschlossen ist, werden gemeinsame Debugging- und Testarbeiten durchgeführt.

Das Schnittstellendokument ist also eigentlich eine Vereinbarung zwischen den beiden Parteien vor der Entwicklung. Normalerweise werden Schnittstellendokumente in Offline- und Echtzeitdokumente unterteilt. Zu den Tools für Offline-Schnittstellendokumente gehören: Word (entspricht Wu), YAPI, Xiaoyaoji usw. Diese Art von Dokument erfordert, dass Programmierer darauf schreiben, und verfügt im Allgemeinen über Schnittstellentestfunktionen. Normalerweise schreiben Entwickler zunächst Informationen in das Offline-Schnittstellendokument und übergeben sie dann zur Referenzentwicklung an das Front-End-Personal. Der größte Nachteil besteht darin, dass wir, wenn sich unser Schnittstellenprogramm ändert, zurückgehen und den oben genannten Inhalt pflegen müssen, was sehr mühsam, wirklich mühsam ist.

Das Echtzeit-Schnittstellendokument kann automatisch das entsprechende Schnittstellendokument basierend auf unserem Code generieren. Der Vorteil besteht darin, dass das generierte Schnittstellendokument automatisch aktualisiert wird, wenn sich unser Code ändert Änderung. Hauptbedarf. Einfach rechtzeitig veröffentlichen. Da er jedoch automatisch basierend auf dem Code generiert wird, besteht der größte Nachteil darin, dass der Code sehr aufdringlich ist und erfordert, dass wir den relevanten Code zum Generieren von Schnittstellendokumenten in den Projektcode integrieren. Es gibt viele Lösungen für die Dokumentation von Echtzeitschnittstellen, aber Swagger ist immer noch eine der einflussreichsten.

2. SpringBoot integriert swagger2

Offizielle Website-Adresse: swagger.io Natürlich ist die offizielle Website auf Englisch, was ziemlich problematisch zu sein scheint. Ich schlage vor, dass Sie einfach meinen Schritten folgen, es ist ganz einfach.

Gleichzeitig möchte ich etwas sagen: Swagger ist in zwei häufig verwendete Versionen unterteilt: Swagger2 und Swagger3. Der Unterschied zwischen den beiden ist nicht sehr groß. Er optimiert hauptsächlich Abhängigkeiten und Anmerkungen. Swagger2 muss zwei JAR-Pakete einführen, und Swagger3 benötigt nur eines. Es gibt keinen großen Unterschied in der Verwendung. Im Folgenden wird swagger2 als Beispiel verwendet.

2.1 Abhängigkeiten einführen

<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.2 Konfiguration einführen

Zuerst müssen Sie eine Anmerkung hinzufügen: @EnableSwagger2. Wir können diese Annotation zur SpringBoot-Startklasse hinzufügen oder eine Konfigurationsklasse anpassen und darauf platzieren. Nach dem Hinzufügen dieser Anmerkung bedeutet dies, dass wir die Swagger-Funktion im Projekt aktiviert haben.

Mit der zweiten Methode definieren wir selbst eine Konfigurationsklasse und können auch eine Docket-Konfiguration hinzufügen. Die sogenannte Docket-Konfiguration ist die Konfiguration einer Reihe von Schnittstellendokumenten (einem Projekt oder einer Version), wie z. B. Einstellungsnamen, Kontakte usw.

Wir fügen eine SwaggerConfig-Klasse unter dem Konfigurationsordner hinzu.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 设置多个：
     *
     * @Bean
     *     public Docket appApi() {
     *
     *         List<Parameter> pars = new ArrayList<>();
     *         ParameterBuilder token = new ParameterBuilder();
     *         token.name("token").description("用户令牌").modelRef(new ModelRef("string")).parameterType("header").required(false)
     *                 .build();
     *         pars.add(token.build());
     *
     *         return new Docket(DocumentationType.SWAGGER_2).select().paths(regex("/app/.*")).build()
     *                 .globalOperationParameters(pars).apiInfo(pdaApiInfo()).useDefaultResponseMessages(false)
     *                 .enable(enableSwagger)
     *                 .groupName("appApi");
     *
     *     }
     *
     *     @Bean
     *     public Docket adminApi() {
     *
     *         List<Parameter> pars = new ArrayList<>();
     *         ParameterBuilder token = new ParameterBuilder();
     *         token.name("token").description("用户令牌").modelRef(new ModelRef("string")).parameterType("header").required(false)
     *                 .build();
     *         pars.add(token.build());
     *         return new Docket(DocumentationType.SWAGGER_2).select().paths(regex("/admin/.*")).build()
     *                 .globalOperationParameters(pars).apiInfo(pdaApiInfo()).useDefaultResponseMessages(false)
     *                 .enable(enableSwagger)
     *                 .groupName("adminApi");
     *
     *     }
     *
     *
     * @return
     */

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.lsqingfeng.action.swagger.controller")).paths(PathSelectors.any())
                .build().globalOperationParameters(setHeaderToken());

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("action-swagger").description("swagger实战").termsOfServiceUrl("")
                .version("1.0").build();
    }

    /**
     * @Description: 设置swagger文档中全局参数
     * @param
     * @Date: 2020/9/11 10:15
     * @return: java.util.List<springfox.documentation.service.Parameter>
     */

    private List<Parameter> setHeaderToken() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder userId = new ParameterBuilder();
        userId.name("token").description("用户TOKEN").modelRef(new ModelRef("string")).parameterType("header")
                .required(true).build();
        pars.add(userId.build());
        return pars;
    }
}

Das Obige ist ein Konfigurationsbeispiel und es ist auch eine setToken-Methode festgelegt, was bedeutet, dass alle Schnittstellen, die Dokumente generieren, einen Token-Parameter vom Header-Typ enthalten müssen.

2.3 Anmerkungen zum Controller hinzufügen

Die direkte Beschreibung unseres Schnittstellendokuments erfolgt hauptsächlich auf Controller-Ebene, z. B. die Funktion dieser Schnittstelle, der Name der Parameter, der Name des Rückgabewerts usw. . Für diese Werte müssen wir den Methoden, Anforderungsparametern und Rückgabeparametern auf dem Controller entsprechende Anmerkungen hinzufügen, damit Swagger uns bei der Generierung der entsprechenden Schnittstellendokumente helfen kann. Dies ist der Eingriff in vorhandenen Code, den ich zuvor erwähnt habe.

Lass uns einen Fall schreiben.

Erstellen Sie zunächst ein VO-Paket, schreiben Sie unsere Anfrage und die entsprechenden Parameter hinein und definieren Sie mit JavaBean die Datenstruktur der Anfrage und Antwort. Beachten Sie, dass die entsprechenden Annotationen hier hinzugefügt werden sollten:

Request-Klasse:

package com.lsqingfeng.springboot.vo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
 * @className: SwaggerReqVO
 * @description:
 * @author: sh.Liu
 * @date: 2022-03-22 19:19
 */
@Data
@ApiModel("创建Swagger请求参数")
public class SwaggerReqVO {

    @ApiModelProperty("id")
    private Integer id;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("性别")
    private Integer gender;
}

Response-Klasse:

package com.lsqingfeng.springboot.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @className: SwaggerResVO
 * @description:
 * @author: sh.Liu
 * @date: 2022-03-22 19:20
 */
@Data
@ApiModel("创建Swagger响应结果")
public class SwaggerResVO {

    @ApiModelProperty("id")
    private Integer id;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("性别")
    private Integer gender;

    @ApiModelProperty("啥啥")
    private String what;
}

Die @ApiModel-Annotation und @@ sind Die hier verwendete ApiModelProperty-Annotation definiert den Namen der Entität und den Namen des Felds, was für die Anzeige beim Generieren von Schnittstellendokumenten praktisch ist.

Schauen wir uns noch einmal den Controller an:

package com.lsqingfeng.springboot.controller;

import com.lsqingfeng.springboot.vo.SwaggerReqVO;
import com.lsqingfeng.springboot.vo.SwaggerResVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

/**
 * @className: SwaggerController
 * @description: swagger 接口测试
 * @author: sh.Liu
 * @date: 2022-03-22 19:18
 */
@RestController
@RequestMapping("/swagger")
@Api(value = "用户接口", tags = {"用户接口"})
public class SwaggerController {

    @ApiOperation("新增用户")
    @PostMapping("save")
    public String save(@RequestBody SwaggerReqVO req) {
        return "success";
    }

    @GetMapping("getById")
    @ApiOperation("根据条件查询用户")
    public SwaggerResVO getById(@RequestBody SwaggerResVO req) {
        return new SwaggerResVO();
    }
}

Die @Api-Annotation und die @ApiOperation-Annotation werden verwendet, um den Schnittstellengruppennamen bzw. den Schnittstellennamen zu markieren. Jetzt starten wir das Projekt.

Ich habe festgestellt, dass dieser Fehler gemeldet wurde.

Wenn man online nach dem Grund sucht, heißt es, dass die SpringBoot2.6-Version nicht mit Swagger2.9.2 kompatibel ist. Einige Leute sagen auch, dass es daran liegt, dass die Version des Guava-Pakets zu niedrig ist.

Ich habe sie alle einzeln ausprobiert und das Problem, die hohe Versionsabhängigkeit von Guava zu ersetzen, besteht immer noch.

Der Hauptgrund für dieses Problem ist tatsächlich, dass die SpringBoot-Version zu hoch ist. Wenn Sie SpringBoot2.5.x und frühere Versionen verwenden, gibt es kein Problem.

Spring Boot 2.6.X verwendet PathPatternMatcher, um Pfade abzugleichen, auf die Swagger verweist. Der von Springfox verwendete Pfadabgleich basiert auf AntPathMatcher.

Um das Problem zu lösen, fügen Sie eine Konfiguration hinzu und ändern Sie den Road-Matching-Modus von springBoot MVC.

Konfiguration in der SpringBoot-Konfigurationsdatei hinzufügen:

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

Wenn es sich um eine Konfigurationsdatei im YML-Format handelt:

#🎜🎜 ## 🎜🎜#Beginnen Sie erneut mit der Problemlösung.

Zugriffsadresse: ip:port number/swagger-ui.html

正常情况就可以看到我们的界面了。一会再说非正常情况。由于我们只给用户接口添加了注解，所有用户接口是可以直接观察中文文档的。而剩下的两个接口，由于没添加注解，所以都是以默认的形式展示的。

点开接口，我们可以看到接口中的想详细信息

点击model,可以看到字段的中文描述。点击 Try it out,就可以直接调试接口。同时注意接口中都让填一个token,这就是我们之前的设置成效了。

截止到目前其实swagger的集成就已经完毕了，主要就是根据我们的注解生成文档，并且可以在线调用调试。开发的时候，我们只需要把Controller这一层的请求和响应，以及方法描述等内容先开发完毕，就可以提供给前端让他们参照开发了。

2.4 [404]问题解决

正常情况我们按照上面的步骤就可以出现页面，但是有些时候可能是由于springBoot的版本过高导致的，我们输入之前的地址，出现404的情况，这个主要是由于项目中无法读取到swagger依赖包下的页面导致的。如果出现了这个问题，我们可以添加一个配置类，让他实现WebMvcConfigurer 接口，在添加一个方法：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

完整代码如下：

package com.lsqingfeng.springboot.config;

import com.lsqingfeng.springboot.interceptor.TokenInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * @className: WebMvcConfig
 * @description:webMvc配置
 * @author: sh.Liu
 * @date: 2022-01-13 09:51
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

这个时候在启动就可以了！

2.5 替换UI

上面的整个过程已经完成了，但是生成的接口文档的页面，其实很多人不太喜欢，觉得不太符合国人的使用习惯，所有又有一些大神，提供了其他的UI测试页面。这个页面的使用还是比较广泛的。

修改方式：只需引入一个依赖包：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

然后把刚才实现的那个的那个方法再添加一条：

registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

完成代码：

package com.lsqingfeng.springboot.config;

import com.lsqingfeng.springboot.interceptor.TokenInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * @className: WebMvcConfig
 * @description:webMvc配置
 * @author: sh.Liu
 * @date: 2022-01-13 09:51
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

//    @Override
//    public void addInterceptors(InterceptorRegistry registry) {
//        //拦截
//        registry.addInterceptor(new TokenInterceptor())
//                .addPathPatterns("/**")
//                .excludePathPatterns("/login");
//    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

重新启动项目： 访问路径发生了变化：** ip:端口号/doc.html**

页面出现了。我们在看看我们的用户接口：

这个风格确实更加的直观，同时也是可以直接进行调试的。大部分的swagger都用的这个风格的文档。

三. SpringBoot集成swagger3

上面已经很详细的讲解了swagger2的集成方式，而swagger3的集成方式更加的简洁一些。

首先引入依赖：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

然后是替换注解： swagger2使用的开启注解是： @EnableSwagger2

而在swagger3中，这个注解要换成： @EnableOpenApi

配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // v2 不同
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // 设置扫描路径
                .build();
    }
}

要注意，里边的版本类型换成了 OAS_30, 就是swagger3的意思。

OAS 是 OpenAPI Specification 的简称，翻译成中文就是 OpenAPI 说明书。

同时访问地址：原始地址，也就是没换UI的地址： localhost:8080/swagger-ui/index.html这个要和swagger2区分开。

swagger3的原始UI风格也发生了一些变化：

同时swagger3也是可以更换UI的。方法和swagger2一样。

四. swaggerUI 拦截器和跨域冲突处理

如果我们的项目中有关于跨域的处理，同时还有拦截器，然后还要使用swagger，这种情况大家要注意了，有可能我们的拦截器会将swagger中的页面路径拦截掉导致swagger页面出不来，当我们在拦截器中把swagger的页面排除掉的时候，也有可能会导致跨域配置的失效。

具体解决方案简单提一下：

拦截器：

/**
 * 拦截器配置
 *
 * @author liuShuai
 */
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
 
    @Bean
    public TokenInterceptor tokenInterceptor() {
        return new TokenInterceptor();
    }
 
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry
                .addInterceptor(tokenInterceptor())
                .addPathPatterns("/**")
                .excludePathPatterns("/user/login")
                .excludePathPatterns("/user/downloadExcel")
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");
    }
 
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

跨域配置：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;
 
/**
 * @className: CorsConfig
 * @description:
 * @author: sh.Liu
 * @date: 2020-12-02 10:16
 */
@Configuration
public class CorsConfig {
 
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOrigin("*");
        config.setAllowCredentials(true);
        config.addAllowedMethod("*");
        config.addAllowedHeader("*");
        UrlBasedCorsConfigurationSource configSource = new UrlBasedCorsConfigurationSource();
        configSource.registerCorsConfiguration("/**", config);
        return new CorsFilter(configSource);
    }
}

用这两种方式去配置，就可以让他们和平共处了。

另： 配套项目代码已托管中gitCode: gitcode.net/lsqingfeng/…

分支： feautre/MybatisPlus

Das obige ist der detaillierte Inhalt vonSpringBoot integrierte Swagger-Beispielanalyse. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!