Springboot整合Swagger2和Swagger3全過程

更新時(shí)間：2024年07月13日 10:45:31 作者：花果水蓮

這篇文章主要介紹了Springboot整合Swagger2和Swagger3全過程,具有很好的參考價(jià)值,希望對(duì)大家有所幫助,如有錯(cuò)誤或未考慮完全的地方,望不吝賜教

一、Swagger2的作用

手寫Api文檔的幾個(gè)痛點(diǎn)：

文檔需要更新的時(shí)候，需要再次發(fā)送一份給前端，也就是文檔更新交流不及時(shí)。
接口返回結(jié)果不明確
不能直接在線測(cè)試接口，通常需要使用工具，比如postman
接口文檔太多，不好管理

Swagger也就是為了解決這個(gè)問題，當(dāng)然也不能說Swagger就一定是完美的，當(dāng)然也有缺點(diǎn)，最明顯的就是代碼移入性比較強(qiáng)。

二、pom依賴:springfox-swagger2、springfox-swagger-ui

<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>${swagger2.version}</version>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>${swagger2.version}</version>
</dependency>

三、Swagger2配置類

@Configuration
@EnableSwagger2 //開啟Swagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("在線教育API文檔")
                .description("本文檔描述了在線教育微服務(wù)接口定義")
                .version("0.0.1-SNAPSHOT")
                .contact(new Contact("java","http://atguigu.com","123456@qq.com"))
                .build();
    }
}

有這兩步就已經(jīng)完成swagger的基本功能，可以訪問http://localhost:{port}/swagger-ui.html，來實(shí)現(xiàn)調(diào)用controller中的接口。如

但實(shí)際上，我們依然可以給controller的類、接口、接口入?yún)⑻砑幼⒔猓?以實(shí)現(xiàn)功能說明的作用。

@Api：修飾整個(gè)類，描述Controller的作用
@ApiOperation：描述一個(gè)類的一個(gè)方法，或者說一個(gè)接口
@ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
@ApiModel：用對(duì)象來接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
@ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)

四、Controller類添加Swagger的注解

@Api(description = "講師管理") //修飾整個(gè)類，描述Controller的作用
@RestController
@RequestMapping("/eduservice/teacher")
public class EduTeacherController {

    @Autowired
    private EduTeacherService eduTeacherService;

    @ApiOperation("查找全部功能")
    @GetMapping("/findall")
    public List<EduTeacher> findAll(){
        List<EduTeacher> list = eduTeacherService.list();
        return list;
    }

    @ApiOperation("邏輯刪除功能")
    @DeleteMapping("{id}") //{id}表示id值通過路徑傳遞
    public void removeById(@PathVariable("id") String id){
        eduTeacherService.removeById(id);
    }
}

再次訪問Swagger-ui，效果如下

五、整合Swagger3配置類

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //PathSelectors.regex("/error.*")選擇器，negate()表示取反
                .paths(PathSelectors.regex("/error.*").negate())
                .build();
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("在線教育API文檔")
                .description("本文檔描述了在線教育微服務(wù)接口定義")
                .version("1.0-SNAPSHOT")
                .build();
    }
}