Java代码生成器02-Swagger的配置问题与使用

阅读数:0次

1. 什么是Swagger

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

好处:

  • 无依赖
    • UI 适用于任何开发环境，无论是本地还是 Web。
  • 人性化
    • 允许最终开发人员轻松交互并尝试您的 API 公开的每一个操作，以便于使用。
  • 易于导航
    • 使用分类整齐的文档快速查找和使用资源和端点。
  • 所有浏览器支持
    • 通过适用于所有主要浏览器的 Swagger UI 迎合所有可能的场景。
  • 完全可定制的
    • 样式并通过完整的源代码访问以您想要的方式调整您的 Swagger UI。
  • 完整的 OAS 支持
    • 可视化 Swagger 2.0 或 OAS 3.0 中定义的 API。

2. 如何使用Swagger

image-20211222045242488

image-20211222051640734

Swagger生成提供给我们的接口测试工具

3. SpringBoot项目整合Swagger

3.1 导入依赖

1
2
3
4
5
6
7
8
9
10
11
12
<!--Swagger-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>3.0.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <!--<version>2.9.2</version>-->
   <version>3.0.0</version>
</dependency>

此处有几处问题需要提一下:

  • springboot项目版本不能过高，过高会有启动不了项目的情况

  • springfox-swagger2的2.9.2版本的guava有两个漏洞，故使用3.0.0最新版修复了漏洞,而且根据使用度选择更为合适(2.9.2Maven仓库地址)

    image-20211222045918667

  • 需要对静态资源加入到静态资源处理器中,不然容易造成404和500错误

    1
    2
    3
    4
    5
    6
    7
    8
    9
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
      // 解决静态资源无法访问
      registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
      // 解决swagger无法访问
      registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
      // 解决swagger的js文件无法访问
      registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

  • springfox-swagger-ui 3.0.0之后换了UI而且改变了请求路径，避免造成404和500错误的配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.
                addResourceHandler( "/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
                .resourceChain(false);
    }

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController( "/swagger-ui/")
                .setViewName("forward:" +  "/swagger-ui/index.html");
    }

3.2 配置文件

此处我将给出2.9.2老版Swagger-ui的配置文件，以及3.0.0新版的配置文件,小呆生成器开源版是使用3.0.0的配置的，如果喜欢老版UI的话可以自行替换修改

  • 2.9.2(SwaggerConfig.java)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig extends WebMvcConfigurationSupport {
        @Bean
        public Docket createRestApi(){
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any()).build();
        }

        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
            .title("小呆代码生成器-开源版-Swagger")
            .description("这是小呆代码生成器的开源版本，欢迎大家加入我们学习了解，同时我们提供一个性价比极高的个性化生成器平台。")
            .version("v1.0")
            .build();
        }

        /**
        * @Author: xingyuchen
        * @Discription: 防止@EnableMvc把默认的静态资源路径覆盖了，手动设置的方式/此处存在两个报错点，springboot版本过高不兼容，静态资源路径被覆盖，swagger2 2.9.2版本有2个漏洞,所以UI使用2.9.2,swagger2用3.0
        * @param registry
        * @Date: 2021/12/22 4:36 上午
        */
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            // 解决静态资源无法访问
            registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
            // 解决swagger无法访问
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            // 解决swagger的js文件无法访问
            			  registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

  • 3.0.0(SwaggerConfig.java)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig extends WebMvcConfigurationSupport {
        @Bean
        public Docket createRestApi(){
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any()).build();
        }

        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
            .title("小呆代码生成器-开源版-Swagger")
            .description("这是小呆代码生成器的开源版本，欢迎大家加入我们学习了解，同时我们提供一个性价比极高的个性化生成器平台。")
            .version("v1.0")
            .build();
        }

        /**
        * @Author: xingyuchen
        * @Discription: 防止@EnableMvc把默认的静态资源路径覆盖了，手动设置的方式/此处存在两个报错点，springboot版本过高不兼容，静态资源路径被覆盖，swagger2 2.9.2版本有2个漏洞,所以UI使用2.9.2,swagger2用3.0
        * @param registry
        * @Date: 2021/12/22 4:36 上午
        */
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.
                    addResourceHandler( "/swagger-ui/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
                    .resourceChain(false);
        }

        @Override
        public void addViewControllers(ViewControllerRegistry registry) {
            registry.addViewController( "/swagger-ui/")
                    .setViewName("forward:" +  "/swagger-ui/index.html");
        }
    }

3.3 接口使用

Controller类(接口归类)

@Api(tags=”Controller标签”)

在Controller类上加入一个Swagger注解：@Api主要是描述这个Controller是哪一个模块的接口

比如:

1
2
3
4
5
6
@RestController
@RequestMapping("/book")
@Api(tags = "图书管理")
public class BookController {
  
}

image-20211222052820517

Controller方法(接口方法)

@ApiOperation(value=”方法解释”)

每个接口方法的标题，我们在每个方法的上面添加一个@ApiOperation注解，描述这个接口方法的功能

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@RestController
@RequestMapping("/book")
@Api(tags = "图书管理")
public class BookController {

    @Autowired
    private BookService bookService;

    @ApiOperation(value = "根据图书ID查询图书")
    @GetMapping("/{id}")
    public Book getOne(@PathVariable(name = "id")Integer id){
        return bookService.getById(id);
    }
}

image-20211222053128936

实体类

@ApiModel(value=”备注”, description=”类描述”)

参数 解释
value 模型的备用名称
description 模型详细的类描述
parent 为模型提供父类以允许描述继承关系

实体属性

@ApiModelProperty(value=”字段说明”,name=”重写属性名字”,required=true/false,hidden=true/fasle)

参数 解释
value 字段说明
name 重写属性名字
dataType 重写属性类型
required 是否必填
example 举例说明
hidden 是否隐藏
allowEmptyValue 是否允许空值
position 允许在模型中显示排序属性
example 属性的示例值

Api注释汇总

作用范围 API 使用情况
对象属性 @ApiModelProperty 用在出入参数对象的字段上
协议集描述 @Api 用于controller类上
协议描述 @ApiOperation 用在controller的方法上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses里边
非对象参数集 @ApiImplicitParams 用在controller的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边
描述返回对象的意义 @ApiModel 用在返回对象类上
赏

谢谢你请我吃糖果

支付宝
微信

扫一扫，分享到微信

微信分享二维码

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

很惭愧<br><br>只做了一点微小的工作<br>谢谢大家