Swagger--基础--2.2--集成Springboot3--swagger3

Swagger–基础–2.2–集成Springboot3–swagger3

---

代码位置

https://gitee.com/DanShenGuiZu/learnDemo/tree/master/swagger_learn/swagger3

1、swagger2到swagger3的注解变化

@Api →@Tag
@ApiIgnore → @Parameter(hidden = true)或者@Parameter(hidden = true)或者@Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") →@ApiResponse(responseCode = "404", description = "foo")

2、代码

User

package feizhou.swagger3.business.business;

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

@Data
@ToString

@Schema(title = "用户实体", description = "用户实体信息")
public class User {
    @Schema(title = "用户id", example = "1")  //推荐的另一种方式
    private String userId;

    @Schema(title = "用户名", example = "张三")
    private String userName;
}

UserController

package feizhou.swagger3.business.business;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "人员信息接口")
@RestController
@RequestMapping("/userController")
public class UserController {


    @Operation(summary = "新增用户", description = "新增用户描述", tags = {"人员信息接口"})
    @RequestMapping(value = "/add", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    //swagger ：在方法位置定义响应参数
    @ApiResponses({
            @ApiResponse(responseCode = "401", description = "请进行身份验证"),
            @ApiResponse(responseCode = "403", description = "拒绝执行"),
            @ApiResponse(responseCode = "404", description = "资源未找到"),
            @ApiResponse(responseCode = "500", description = "系统异常")
    })
    //swagger ：在参数位置定义请求参数
    public Integer add(@Parameter(name = "user", description = "用户实体参数", required = true) @RequestBody User user) {
        return 1;
    }

    @RequestMapping(value = "/update", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    @Operation(summary = "修改", description = "修改用户描述", tags = {"人员信息接口"})
    @Parameters({
            @Parameter(name = "userId", description = "用户id", example = "1", required = true),
            @Parameter(name = "userName", description = "用户名称", example = "1", required = true)
    })
    //swagger ：在方法位置定义请求参数
    public Integer update(@RequestParam("userId") String userId, @RequestParam("userId") String userName) {
        return 1;
    }


    @Operation(summary = "删除", description = "删除用户描述", tags = {"人员信息接口"})
    @RequestMapping(value = "/delete", method = RequestMethod.DELETE)
    //swagger ：在参数位置定义请求参数
    public Integer delete(@Parameter(name = "userId", description = "需要删除的用户id", required = true) @RequestParam("userId") String userId) {
        return 1;

    }


    @Operation(summary = "查询", description = "查询用户", tags = {"人员信息接口"})
    @Parameters({
            @Parameter(name = "userId", description = "用户标识", required = true)
    })
    @RequestMapping(value = "/query", method = RequestMethod.GET)
    public String query(@RequestParam("userId") String userId) {
        return userId;
    }

}

SwaggerConfig

package feizhou.swagger3.business.config;


import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;

import java.util.Arrays;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI1() {//默认OpenAPI
        Contact contact = new Contact();
        contact.setEmail("9207867312");
        contact.setExtensions(null);
        contact.setName("zhoufei");
        contact.setUrl("http");
        return new OpenAPI()
                .info(new Info().title("swagger3.0")
                        .contact(contact)
                        .description("描述信息")
                        .version("版本 v0.0.1")
                        .license(new License().name("Apache 2.0").url("Apache 2.0的链接地址")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("外部文档对应的URl"));
    }

    @Bean("group1")
    public GroupedOpenApi group1() {
        String[] packagedToMatch = {
                "feizhou.xcoa.project.em"
        };
        return GroupedOpenApi.builder().group("人员组")//定义一个组名称
                .packagesToScan(packagedToMatch)//包扫描路径
                .pathsToMatch("/api/em/**", "/api/em-open/v1/**")//扫描路径
                .packagesToExclude("feizhou.xcoa.product",//排除哪些包
                        "feizhou.business",
                        "feizhou.app",
                        "feizhou.test"//OA
                ).addOpenApiCustomizer(openApi -> {
                    openApi.setInfo(new Info().title("文档1").description("文档1的描述").version("1.0.0"));
                    openApi.addSecurityItem(
                            new SecurityRequirement().addList("bearer-jwt", Arrays.asList("read", "write")));
                    openApi.getComponents().addSecuritySchemes("bearer-jwt", new SecurityScheme()
                            .type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.HEADER).name("Authorization"));
                }).build();


    }

    @Bean
    public GroupedOpenApi group2() {
        return GroupedOpenApi.builder()
                .group("机构组")//定义一个组名称
                .pathsToMatch("/admin/**")//扫描路径
                .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Component.class))//方法注解过滤
                .build();
    }
}

application.yml

server:
  port: 8787
 

pom.xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<!-- swagger 3.0 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

3、测试

http://localhost:8787/swagger-ui/index.html