Spring Boot - swagger

柔光的暖阳◎ 2023-10-13 09:02 38阅读 0赞

## Swagger2配置 ##

package com.lfsun.springbootswagger.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    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;
    
    /**
     * <p>
     * Swagger2 配置
     * </p>
     */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
        
    
        @Bean
        public Docket createRestApi() {
        
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.lfsun.springbootswagger.controller")).paths(PathSelectors.any()).build();
        }
    
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder().title("spring-boot-demo").description("这是一个简单的 Swagger API 演示").contact(new Contact("lfsun", "https://lfsun666.blog.csdn.net/", "XXXXX@qq.com")).version("1.0.0-SNAPSHOT").build();
        }
    
    }

## Controller ##

package com.lfsun.springbootswagger.controller;
    
    
    import com.lfsun.springbootswagger.common.ApiResponse;
    import com.lfsun.springbootswagger.common.DataType;
    import com.lfsun.springbootswagger.common.ParamType;
    import com.lfsun.springbootswagger.entity.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import lombok.extern.slf4j.Slf4j;
    import org.springframework.web.bind.annotation.*;
    import org.springframework.web.multipart.MultipartFile;
    
    import java.util.List;
    
    /**
     * <p>
     * User Controller
     * </p>
     */
    @RestController
    @RequestMapping("/user")
    @Api(tags = "1.0.0-SNAPSHOT", description = "用户管理", value = "用户管理")
    @Slf4j
    public class UserController {
        
        @GetMapping
        @ApiOperation(value = "条件查询（DONE）", notes = "备注")
        @ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", dataType = DataType.STRING, paramType = ParamType.QUERY, defaultValue = "xxx")})
        public ApiResponse<User> getByUserName(String username) {
        
            log.info("多个参数用  @ApiImplicitParams");
            return ApiResponse.<User>builder().code(200).message("操作成功").data(new User(1, username, "JAVA")).build();
        }
    
        @GetMapping("/{id}")
        @ApiOperation(value = "主键查询（DONE）", notes = "备注")
        @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH)})
        public ApiResponse<User> get(@PathVariable Integer id) {
        
            log.info("单个参数用  @ApiImplicitParam");
            return ApiResponse.<User>builder().code(200).message("操作成功").data(new User(id, "u1", "p1")).build();
        }
    
        @DeleteMapping("/{id}")
        @ApiOperation(value = "删除用户（DONE）", notes = "备注")
        @ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH)
        public void delete(@PathVariable Integer id) {
        
            log.info("单个参数用 ApiImplicitParam");
        }
    
        @PostMapping
        @ApiOperation(value = "添加用户（DONE）")
        public User post(@RequestBody User user) {
        
            log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
            return user;
        }
    
        @PostMapping("/multipar")
        @ApiOperation(value = "添加用户（DONE）")
        public List<User> multipar(@RequestBody List<User> user) {
        
            log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
    
            return user;
        }
    
        @PostMapping("/array")
        @ApiOperation(value = "添加用户（DONE）")
        public User[] array(@RequestBody User[] user) {
        
            log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
            return user;
        }
    
        @PutMapping("/{id}")
        @ApiOperation(value = "修改用户（DONE）")
        public void put(@PathVariable Long id, @RequestBody User user) {
        
            log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 ");
        }
    
        @PostMapping("/{id}/file")
        @ApiOperation(value = "文件上传（DONE）")
        public String file(@PathVariable Long id, @RequestParam("file") MultipartFile file) {
        
            log.info(file.getContentType());
            log.info(file.getName());
            log.info(file.getOriginalFilename());
            return file.getOriginalFilename();
        }
    }

## 完整代码案例地址 ##

[Spring Boot 集成 swagger][Spring Boot _ swagger]

[Spring Boot _ swagger]: https://gitee.com/lfsun666/springboot-study-2023/tree/master/spring-boot-swagger