Spring boot - 集成Swagger2

Posted 2022-10-27 zhoux955792

最近公司项目用到的API 接口测试工具Swagger，以前貌似没有接触过，上手的接口测试工具postman，所以这里赶紧恶补一下......

1.添加Swagger2所需要的依赖：

<!-- 添加Spring boot Swagger2 依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>

2.项目中添加一个SwaggerConfig类：

package com.xianwen.sp.springjtool.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author : zhoux
 * 
 *  Configuration Swagger2 for this project.
 *  
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig 
    
    @Bean
    public Docket creatRestApi () 
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("spring jtool")
                .apiInfo(getApiInfo())
                .select()
                 //设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.xianwen.sp.springjtool.controller"))
                //只有标记了@ApiOperation的方法才会暴露出给swagger
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())//PathSelectors.regex("/api/.*")
                .build();
    
    
    private ApiInfo getApiInfo() 
        return new ApiInfoBuilder()
                .title("API Document")
                .description("Swagger2 API Document")
                //.contact(new Contact("zhoux", "http://localhost/swagger-ui.html", "[e-mail]")) 
                .version("1.0.0")
                .build();
    

3.在controller中使用 @Api(tag = "*****")注解标记，需要测试的接口方法使用 @ApiOperation("*****") 注解标记：

package com.xianwen.sp.springjtool.controller;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.xianwen.sp.springjtool.entity.User;
import com.xianwen.sp.springjtool.service.impl.UserServiceImpl;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

/**   
 * @ClassName:  UserController   
 * @Description:  the controller for user.
 * 
 * @author: zhoux 
 * 
 * @date:  2019-9-10  10:10:59  
 *     
 */
@Api(description = "用户管理 - 用户数据")
@RestController
@RequestMapping("/user")
public class UserController 
    
    @Autowired
    private UserServiceImpl mUserServiceImpl;
    
    @ApiOperation("获取所有的用户信息")
    @PostMapping(value = "/findUser", produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public List<User> findAllUser() 
        return mUserServiceImpl.findAllUser();
    
    
    @ApiOperation("根据id获取用户信息")
    @GetMapping(value = "/id", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public List<User> findAllById(@PathVariable("id") Long id) 
        return mUserServiceImpl.findById(id);
    
    
    @ApiOperation("根据name获取用户信息")
    @GetMapping(value = "/name", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public List<User> findAllByName(@PathVariable("name") String name) 
        return mUserServiceImpl.findByName(name);