SpringBoot 集成 Swagger 文档及自定义访问路径

一、Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

二、SpringBoot 集成使用

1. pom

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. SwaggerConfig.java

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bxc.conformity.Swagger.DemoController"))
//                .paths(PathSelectors.regex("/App/.*|Thirdparty/.*"))
                .paths(PathSelectors.regex("(/App/.*)|(/Thirdparty/.*)"))
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList = new ArrayList();
        apiKeyList.add(new ApiKey("Token", "token", "header"));
        return apiKeyList;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Token", authorizationScopes));
        return securityReferences;
    }

    private ApiInfo apiInfo() {
//     访问地址   http://localhost:8085/swagger-ui.html
        return new ApiInfoBuilder()
                .title("接口文档 1.0.0")
                .description("哈哈网络科技有限公司")
                .version("1.0.0")
                .build();
    }
}

3. 使用

@Api(tags = "接口")
@RestController
@RequestMapping("/App")
public class SwController {

    @ApiOperation(value = "添加用户",
            notes = "  username        用户名 \n" +
                    "passwd          密码 \n" +
                    "company         公司名称 \n" +
                    "child_number    子用户个数 \n"
    )
    @PostMapping("/AddUser")
    public ResponseTemplate AddUser(
            @RequestBody
            @ApiParam(value = "{\"username\":\"test2\",\"passwd\":\"test\",\"company\":\"哈哈网络\",\"child_number\":10}")
                    UserEntity user,
            HttpServletRequest request) {

        return ResSuccessTemplate.builder().build();
    }


    @ApiOperation("获取用户")
    @ApiImplicitParams(
            {
                    @ApiImplicitParam(name = "userid", value = "用户的id", required = true)
            }
    )
    @GetMapping("/getUser/{userid}")
    public ResponseTemplate GetRootChildNumberMax(@PathVariable("userid") int userid) {

        return ResSuccessTemplate.builder().build();
    }
}

@ApiModel
@Mapper
public class UserEntity {
    @ApiModelProperty(hidden= true)
    private int id;

    @ApiModelProperty(hidden= true)
    private String username;
    
    @ApiModelProperty(value = "需求主题")
    private String age;

    @ApiModelProperty(hidden= true)
    @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
    private String passwd;
  }

三、SpringBoot 自定义 Swagger-UI

1. 下载 swagger-ui

https://github.com/swagger-api/swagger-ui/tree/v3.18.3

下面可以进行一些自定义的修改。

2. 配置数据转发

@Controller
@RequestMapping("/my")
public class SwaggerController {

    @GetMapping("/v2/api-docs")
    public void  swagger(HttpServletRequest request, HttpServletResponse response){
        String url = "/v2/api-docs";
        System.out.println(url);
        try {
            request.getRequestDispatcher(url).forward(request,response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

3. 将解压后打包好的dist文件夹改名称为 my，并将修改后的文件夹复制到static下。
4. 修改 static/my/index.html

将 url: "https://petstore.swagger.io/v2/swagger.json"
修改为：url: "/my/v2/api-docs"

修改引用：

<script src="/my/swagger-ui-bundle.js"> </script>
<script src="/my/swagger-ui-standalone-preset.js"> </script>

5. 重新打开项目便以生效。

四、SpringSecurity 放行 Swagger

@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring().antMatchers("/register/**")
            // swagger2 UI 放行
            .antMatchers("/css/**", "/js/**", "/img/**", "/index.html", "favicon.ico",
                    "/doc.html", "/webjars/**", "/swagger-resources/**", "/v2/api-docs/**", "/ws/**","/swagger-ui.html");
}

五、使用 springdoc

springdoc 支持OpenApi规范，支持SpringBoot3规范。

添加依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.8</version>
</dependency>

增加配置：

springdoc:
  swagger-ui:
    path: /swagger
  packages-to-scan: com.bxc.controller
  paths-to-match: /*

配置 OpenAPI：

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("SpringShop API")
                        .description("Spring shop sample application")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringShop Wiki Documentation")
                        .url("https://springshop.wiki.github.org/docs"));
    }
}

浏览器访问：http://localhost:8081/swagger