swagger 3.0 学习笔记

引入pom

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-boot-starterartifactId>
            <version>3.0.0version>
        dependency>

配置

import io.swagger.models.auth.In;
import io.swagger.v3.oas.annotations.Operation;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;

@Configuration
public class SwaggerConfig
{
    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes()
    {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
        apiKeyList.add(new ApiKey("Head", "Head", In.HEADER.toValue()));
        apiKeyList.add(new ApiKey("Query", "Query", In.QUERY.toValue()));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts()
    {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth()
    {
        AuthorizationScope[] authorizationScopes ={new AuthorizationScope("global", "accessEverything")} ;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        securityReferences.add(new SecurityReference("Head", authorizationScopes));
        securityReferences.add(new SecurityReference("Query", authorizationScopes));
        return securityReferences;
    }

     @Bean
      public Docket swagger3() {
          return new Docket(DocumentationType.OAS_30)
                  .select()
                  .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
                  .paths(PathSelectors.regex("/test.*"))
                  .build()
                  .groupName("swagger3.0")
                  .securitySchemes(securitySchemes())
                  .securityContexts(securityContexts())
                  .apiInfo(apiInfo());
      }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：XXX系统_接口文档")
                // 描述
                .description("描述：xxxx.")
                // 作者信息
                .contact(new Contact("作者信息", null, null))
                // 版本
                .version("版本号: >...>")
                .build();
    }
}

可以加上全局请求参数

对象

ReqSwagger3VO

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

import java.io.Serializable;
import java.util.List;

@Data
@Schema(name="ReqSwagger3VO",description ="swagger3对象" )
public class ReqSwagger3VO implements Serializable {
    private static final long serialVersionUID = 646541L;

    @Schema(description = "字符串",example = "aaaa")
    private String dataStr;

    @Schema(description = "数字",example = "1111")
    private Integer dataInt;

    @Schema(description = "字符数组" )
    private List<String> listStr;

    @Schema(description = "数字数组")
    private List<Integer> listInt;

    @Schema(description = "用户")
    private User user;
    @Schema(description = "用户数组")
    private  List<User> userList;

    @Schema(hidden = true)
    private String hiddenStr;
    private String hiddenNotStr;
}

User

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
//https://www.cnblogs.com/antLaddie/p/17418078.html
@Schema(description ="用户信息" )
@Data
@AllArgsConstructor
public class User {
    @Schema(description = "姓名",example = "张三")
    private String name;
    @Schema(description = "年龄",example = "18", format = "int32")
    private int age;
    @Schema( description = "学生分数属性", format = "double", example = "55.50")
    private Double fraction;
}

控制层

example 赋值问题还没解决

import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.apache.commons.io.IOUtils;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletResponse;
import java.io.ByteArrayOutputStream;
import java.io.StringWriter;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;

@RestController
@RequestMapping("/test/swagger")
@Tag(name = "接口类描述name",description = "接口类描述desc")
public class SwaggerController {

    @Operation(summary = "get请求")
    @GetMapping("{pathParam}/get")
    public Object get(
            @Parameter(description="reqParam参数描述",  schema = @Schema(allowableValues = {"aaa", "22222"}))
            @RequestParam String reqParam,
            @Parameter(description="pathParam参数描述",example = "111")
            @PathVariable Integer pathParam,
            @Parameter(description="headParam参数描述", schema = @Schema(allowableValues = {"888888"}))
            @RequestHeader Long headParam
    ){
        return null;
    }

    @Operation(summary = "get2请求,example赋值不生效",parameters={
            @Parameter(ref="reqParam",name = "reqParam",description="reqParam参数描述",in= ParameterIn.QUERY,  schema = @Schema(allowableValues = {"aaa", "22222"})),
            @Parameter(ref="pathParam", name = "pathParam",description="pathPatam参数描述",in= ParameterIn.PATH,schema = @Schema(allowableValues = {"11111", "333"})),
            @Parameter(ref="headParam", name = "headParam",description="headParam参数描述",in= ParameterIn.PATH,schema = @Schema(allowableValues = {"11111", "333"}))
    })
    @GetMapping("/2/{pathParam}/get")
    public Object get2(@RequestParam String reqParam,@PathVariable Integer pathParam ,@RequestHeader Long headParam){
        return null;
    }

    @Operation(summary = "post请求")
    @PostMapping("/post")
    public Object post(@RequestBody ReqSwagger3VO reqSwaggerVO){
        return null;
    }


    @Hidden
    @PostMapping("/hidden")
    public Object hidden(@RequestBody ReqSwaggerVO reqSwaggerVO){
        return null;
    }


    @Operation(summary = "文件上传")
    @PostMapping(value = "/upload")
    public Object uploadFile(@RequestParam(value = "file") @RequestPart MultipartFile file){

        return null;
    }

    @Operation(summary = "zip下载")
    @PostMapping(value = "/zip/download")
    public void downloadZip(HttpServletResponse response)throws Exception {

        String fileName ="file.zip";

        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
        ZipOutputStream zip = new ZipOutputStream(outputStream);

        for (int i = 0; i < 2; i++) {
            StringWriter sw = new StringWriter();
            sw.append("11111a"+i);
            sw.append("2222c"+i);
            // 添加到zip
            zip.putNextEntry(new ZipEntry(i+"name.txt"));
            IOUtils.write(sw.toString(), zip, "UTF-8");
            IOUtils.close(sw);
            zip.flush();
            zip.closeEntry();
        }

        IOUtils.close(zip);
        byte[] data = outputStream.toByteArray();

        response.reset();
        response.addHeader("Access-Control-Allow-Origin", "*");
        response.addHeader("Access-Control-Expose-Headers", "Content-Disposition");
        response.setHeader("Content-Disposition", "attachment; filename=\""+fileName+"\"");
        response.addHeader("Content-Length", "" + data.length);
        response.setContentType("application/octet-stream; charset=UTF-8");
        IOUtils.write(data, response.getOutputStream());
    }

}