基于代码生成器Swagger的应用

最新推荐文章于 2024-04-17 09:58:54 发布

打小就很皮...

最新推荐文章于 2024-04-17 09:58:54 发布

阅读量422

点赞数 7

文章标签： java spring boot

本文链接：https://blog.csdn.net/qq_70172010/article/details/135044588

版权

当涉及到后端开发和API文档的设计，Swagger是一个非常强大的工具。Swagger是一种用于描述、生产、消费和可视化RESTful风格的Web服务的工具。在这篇博客中，我将介绍Swagger的基本概念以及如何在后端开发中使用Swagger来设计和管理API文档。

1.什么是Swagger？

Swagger是一种开源的API框架，用于设计、构建、文档化和消费RESTful风格的Web服务。它允许开发者在不需要访问实际服务的情况下定义API的结构和细节。Swagger的核心是一个用于描述API的标准格式，以及一组工具，可以根据该格式生成交互式文档、客户端SDK等。

2.Swagger的基本组成部分

OpenAPI Specification（OAS）: Swagger的规范基于OpenAPI Specification，它定义了API的结构和元数据。这包括API的端点、参数、请求和响应格式等。

Swagger UI: Swagger UI是一个基于HTML、CSS和JavaScript的前端界面，用于可视化和交互式地显示API文档。开发者可以通过Swagger UI直观地了解API的使用方式。

Swagger Editor: Swagger Editor是一个用于编辑和验证OpenAPI规范的在线编辑器。它提供了一个直观的界面，使开发者能够轻松地创建和编辑API文档。

3.如何在后端开发中应用Swagger？

步骤1：集成Swagger依赖

在后端项目中，首先需要集成Swagger的依赖。这通常包括在项目的构建文件中添加Swagger相关的库和插件，以确保Swagger能够与后端服务进行集成。

 <!-- 引入 Swagger 依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

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

        <!--        Knife4j ui美化-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.7</version>
        </dependency>

以下是添加了ui美化后的效果（基于我的展示效果）

步骤2：配置Swagger

1.配置Swagger-ResourcesConfig类

可根据实际情况修改

package com.gcxy.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class  ResourcesConfig implements WebMvcConfigurer
{

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry)
    {

        /** swagger配置 */
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2.Swagger2的接口配置-SwaggerConfig类

可根据实际情况修改

package com.gcxy.config;

import java.util.ArrayList;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2的接口配置
 *
 * @author deng
 */
@Configuration
@EnableSwagger2 //标记项目启用 Swagger API 接口文档
public class SwaggerConfig
{

    /** 是否开启swagger */
    @Value("${swagger.enabled}")
    private boolean enabled;

    /** 设置请求的统一前缀 */
    @Value("${swagger.pathMapping}")
    private String pathMapping;

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {   // 创建Docket对象
        return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用Swagger2
                // 是否启用Swagger
                .enable(enabled)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                // 设置Api信息
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                // .apis(RequestHandlerSelectors.basePackage("com.project.tool.swagger"))
                // 扫描所有
                .paths(PathSelectors.any())
                // 构建出 Docket 对象
                .build()
                /* 设置安全模式，swagger可以设置访问token */
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                .pathMapping(pathMapping);
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes()
    {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "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;
    }

    /**
     * 默认的安全上引用
     */
    private 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("Authorization", authorizationScopes));
        return securityReferences;
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：Swagger测试_接口文档")
                // 描述
                .description("描述：用于管理项目人员信息,具体包括XXX,XXX模块...")
                // 作者信息
                .contact(new Contact("deng", null, null))
                // 版本
                .version("版本号:1.0" )
                .build();
    }
}

步骤3：定义API文档

具体的请求接口可根据实际需求进行创建

简单示例：

package com.gcxy.controller;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

/**
 * <p>
 *  前端控制器
 * </p>
 *
 * @author dengjie
 * @since 2023-12-11
 */
@Api("手机信息管理")
@RestController
@RequestMapping("/phone")
public class PhoneController {
    @ApiOperation("Swagger测试接口")
//    @GetMapping("test")GetMapping注解只会创建get请求的接口
    @RequestMapping("test")//RequestMapping注解会创建所有的请求接口
    public void test(){
        System.out.println("这是一个测试接口！！！");
    }

}