Swagger2使用教程

魚迹

发布于 2023-05-06 21:35:13

9430

发布于 2023-05-06 21:35:13

Swagger2使用教程

1、简介

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，后来成为了 Open API 标准的主要定义者。对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法。

Swagger 主要包含了以下三个部分：

名称	说明
Swagger Editor	基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范
Swagger UI	它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档
Swagger Codegen	可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

2、springboot集成Swagger 2

SpringBoot项目整合swagger需要用到两个依赖：springfox-swagger2和springfox-swagger-ui，用于自动生成swagger文档。

springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。在pom.xml文件中添加依赖：

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

3、编写配置类

以下是一个配置类的使用简单示例：

package com.alex.shopping.config;

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.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * swagger2 文档生成
 * 路径:ip:port/swagger-ui.html
 */
@Configuration
public class Swagger2Configuration {

//        版本号
    private static final String VERSION="0.1.0";
   
    /**
     * 接口
     * @return
     */
    @Bean
    public Docket userApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(userApiInfo())//调用apiInfo方法，创建一个ApiInfo实例，里面是展示在文档页面信息内容
                .select()//返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
                .apis(RequestHandlerSelectors.basePackage("com.it.mall.controller"))//扫描的包路径
                .paths(PathSelectors.any())//路径判断
                .build()//创建
                .groupName("接口");//分组名称
    }
    private ApiInfo userApiInfo(){
        return new ApiInfoBuilder()//创建ApiInfoBuilder实例
                .title("project-name")//标题
                .description("接口文档")//描述
                .version(VERSION)//版本号
                .build();//创建
    }
}

注意： 对于需要实现swagger的开启与关闭，不要使用上述代码。对于生产环境，开启swagger可能会导致api暴露而产生的安全问题。并且要注意扫描包的位置更改。

4、一些常用注解

注解	作用
@Api	用在controller类，描述API接口
@ApiOperation	描述接口方法
@ApiModel	描述对象
@ApiModelProperty	描述对象属性
@ApiImplicitParams	描述接口参数
@ApiResponses	描述接口响应
@ApiIgnore	忽略接口方法