简单入手Swagger

素颜马尾好姑娘i 2022-12-02 10:51 190阅读 0赞

### 简单入手Swagger ###

*  swagger的出现原因：
 *  1，swagger的介绍
 *   *  1.1功能
     *   *  1.1.1 可以引用本地的json,yml文件，也可以新建，编写完成后下载
         *  1.1.2 在线测试
         *  1.1.3 api文档
 *  2，使用场景
 *  3，springBoot整合Swagger
 *   *  3.1添加pom依赖包
     *  3.2 swagger的配置
 *  4，主要会使用到的几个注解参数
 *   *  4.1 一些常用参数的例子
     *   *  \*\*@Api()\*\*
         *  \*\*@ApiOperation()用于方法；表示一个http请求的操作
         *   *  @ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
         *  @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
 *  5 项目流程
 *  6 配合mabatis-plus可以自动生成注解
 *  7 gitlub 上的代码地址

# swagger的出现原因： #

![在这里插入图片描述][20200903162926348.png_pic_center]  
1，降低沟通上的成本  
2，数据结构及时变化的知晓

# 1，swagger的介绍 #

1，swagger的官网：[https://swagger.io/][https_swagger.io]  
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

**swagger的优点：**  
**对于后端**

*  开发人员来说，不用手写wiki接口拼大量的参数，避免手写错误
 *  对代码的倾入性低，采用全注解的方式，开发简单
 *  方法参数名修改、增加、减少参数都可以直接生效，不用手动维护。
 *  减少对输出api文档的书写  
    缺点就是：增加了开发成本，写接口还得再写一套参数配置  
    **对于前端**  
    后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然

联调方便，如果出了问题，直接测试接口，实时检查参数和返回值，就可以快速定位是前端问题还是后端问题。  
**对于测试**  
对于某些没有前端界面的UI功能，可以用来测试接口。  
操作简单、不用了解具体代码就可以操作

## 1.1功能 ##

### 1.1.1 可以引用本地的json,yml文件，也可以新建，编写完成后下载 ###

### 1.1.2 在线测试 ###

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center]

### 1.1.3 api文档 ###

请求参数：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 1]  
返回参数：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 2]

# 2，使用场景 #

前后端联调，代码测试，api文档输出

# 3，springBoot整合Swagger #

## 3.1添加pom依赖包 ##

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

## 3.2 swagger的配置 ##

package com.sike.okya.web.client.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.context.annotation.Profile;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.schema.ModelRef;
    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;
    
    import java.util.ArrayList;
    import java.util.Collections;
    import java.util.List;
    
    /** * @author evanYang * @version 1.0 * @date 09/29/2019 11:30 */
    @Configuration
    @EnableSwagger2
    @Profile({ "dev","test","local"})
    public class SwaggerConfig { 
    
    
        @Bean
        public Docket api() { 
            ParameterBuilder ticketPar = new ParameterBuilder();
            ParameterBuilder ticketParAppType = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<Parameter>();
            ticketPar.name("UUID").description("手机唯一标识")//name表示名称，description表示描述
                    .modelRef(new ModelRef("string")).parameterType("header")
                    //.required(false).build();
                    .required(false).defaultValue("uuid").build();//required表示是否必填，defaultvalue表示默认值
            ticketParAppType.name("appType").description("app类型")//name表示名称，description表示描述
                    .modelRef(new ModelRef("string")).parameterType("header")
                    //.required(false).build();
                    .required(false).defaultValue("tpi").build();//required表示是否必填，defaultvalue表示默认值
            pars.add(ticketPar.build());//添加完此处一定要把下边的带***的也加上否则不生效
            pars.add(ticketParAppType.build());
    
            return new Docket(DocumentationType.SWAGGER_2).
                    useDefaultResponseMessages(false)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.regex("^(?!auth).*$"))
                    .build()
                    .securitySchemes(securitySchemes())
                    .securityContexts(securityContexts())
                    .globalOperationParameters(pars)
                    ;
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("客户端文档")
                    .description("客户端api文档")
    // .termsOfServiceUrl("/")
                    .version("1.0")
                    .build();
        }
        private List<ApiKey> securitySchemes() { 
            ArrayList arrayList = new ArrayList(Collections.singleton(new ApiKey("Authorization", "Authorization", "header")));
            //arrayList.add(Collections.singleton(new ApiKey("UUID", "UUID", "header")));
            return arrayList;
        }
        private List<SecurityContext> securityContexts() { 
            return new ArrayList(
                    Collections.singleton(SecurityContext.builder()
                            .securityReferences(defaultAuth())
                            .forPaths(PathSelectors.regex("^(?!auth).*$"))
                            .build())
            );
        }
        List<SecurityReference> defaultAuth() { 
            AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
            AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
            authorizationScopes[0] = authorizationScope;
            ArrayList authorization = new ArrayList(Collections.singleton(new SecurityReference("Authorization", authorizationScopes)));
            //authorization.add(Collections.singleton(new SecurityReference("Authorization", authorizationScopes)));
            return authorization;
        }
    
        public static void main(String[] args) { 
        }
    }

这里主要配置是：

*  @EnableSwagger2注解启用Swagger2
 *  Docket Bean  
    这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议
 *  token的配置  
    securitySchemes(securitySchemes())，请求方法中都会带token
 *  head的配置和默认参数设置  
    ticketPar.name(“UUID”).description(“手机唯一标识”)//name表示名称，description表示描述  
    .modelRef(new ModelRef(“string”)).parameterType(“header”)  
    //.required(false).build();  
    .required(false).defaultValue(“uuid”).build();//required表示是否必填，defaultvalue表示默认值
 *  Profile的配置  
    @Profile(\{“dev”,“test”,“local”\}) 哪些环境下可以访问

**相应结果类：**

package com.evan.swaggerdemo.common;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    /** * 请求响应结果 * * @author EvanYang * * @param <T> */
    @ApiModel(description = "返回对象")
    @Data
    public class Response<T> extends BaseResp{ 
    	public final static String CODE_OK = "200";
    	public final static String MSG_OK = "ok";
    	public final static String CODE_ERROR = "5000";
    	public final static String MSG_ERROR = "error";
    	@ApiModelProperty(value = "返回码，200为成功，其他为失败", required = true)
    	private String resultCode;
    	@ApiModelProperty(value = "返回码描述", required = true)
    	private String resultMsg;
    	@ApiModelProperty(value = "结果签名", required = true)
    	private String sign;
    	@ApiModelProperty(value = "详细数据", required = false)
    	private T data;
    
    	public Response() { 
    		resultCode = CODE_OK;
    		resultMsg = MSG_OK;
    	}
    
    	public Response(String resultCode, String resultMsg) { 
    		this.resultCode = resultCode;
    		this.resultMsg = resultMsg;
    	}
    
    	/** * 成功结果 * * @param data * @param <T> * @return */
    	public static <T> Response<T> ok(T data, String sign) { 
    		Response<T> response = new Response<>();
    		response.setData(data);
    		response.setSign(sign);
    		return response;
    	}
    
    	/** * 成功结果 * * @param data * @param <T> * @return */
    	public static <T> Response<T> ok(T data) { 
    		Response<T> response = new Response<>();
    		response.setData(data);
    		return response;
    	}
    
    
    	/** * 失败结果 * * @param data * @param <T> * @return */
    	public static <T> Response<T> error(T data) { 
    		Response<T> response = new Response<>();
    		response.setData(data);
    		return error(CODE_ERROR, MSG_ERROR, data);
    	}
    
    	/** * 失败结果 * * @param code * @param msg * @param data * @param <T> * @return */
    	public static <T> Response<T> error(String code, String msg, T data) { 
    		Response<T> response = new Response<>(code, msg);
    		response.setData(data);
    		return response;
    	}
    
    	/** * 失败结果 * * @param data * @param <T> * @return */
    	public static <T> Response<T> error(Exception exception, T data) { 
    		return errorException(exception, data);
    	}
    
    	/** * 失败结果 * @param data * @param <T> * @return */
    	public static <T> Response<T> errorException(Exception exception, T data) { 
    		Response<T> response = new Response<>();
    		response.setData(data);
    		response.setResultMsg(exception.getMessage());
    		return response;
    	}
    }

# 4，主要会使用到的几个注解参数 #

常用注解：

*  @Api()用于类；  
    表示标识这个类是swagger的资源
 *  @ApiOperation()用于方法；  
    表示一个http请求的操作
 *  @ApiParam()用于方法，参数，字段说明；  
    表示对参数的添加元数据（说明或是否必填等）
 *  @ApiModel()用于类  
    表示对类进行说明，用于参数用实体类接收
 *  @ApiModelProperty()用于方法，字段  
    表示对model属性的说明或者数据操作更改
 *  @ApiIgnore()用于类，方法，方法参数  
    表示这个方法或者类被忽略
 *  @ApiImplicitParam() 用于方法  
    表示单独的请求参数
 *  @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

## 4.1 一些常用参数的例子 ##

*  List item

### **@Api()** ###

用于类；表示标识这个类是swagger的资源  
tags–表示说明  
value–也是说明，可以使用tags替代  
但是tags如果有多个值，会生成多个list

@RestController
    @RequestMapping("/userModel")
    @Api(value="用户controller",tags={ "用户操作接口"})
    public class UserController {

*  效果图

![在这里插入图片描述][20200830145613194.png_pic_center]

### \*\*@ApiOperation()用于方法；表示一个http请求的操作 ###

value用于方法描述  
notes用于提示内容  
tags可以重新分组（视情况而用）  
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）  
name–参数名  
value–参数说明  
required–是否必填

#### @ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 ####

value–表示对象名  
description–描述  
都可省略

### @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 ###

value–字段说明  
name–重写属性名字  
dataType–重写属性类型  
required–是否必填  
example–举例说明  
hidden–隐藏

# 5 项目流程 #

*  项目初始阶段

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 3]

*  项目迭代阶段

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 4]

# 6 配合mabatis-plus可以自动生成注解 #

package com.evan.springboot;
    
    import com.baomidou.mybatisplus.annotation.DbType;
    import com.baomidou.mybatisplus.annotation.FieldFill;
    import com.baomidou.mybatisplus.annotation.IdType;
    import com.baomidou.mybatisplus.core.exceptions.MybatisPlusException;
    import com.baomidou.mybatisplus.core.toolkit.StringPool;
    import com.baomidou.mybatisplus.core.toolkit.StringUtils;
    import com.baomidou.mybatisplus.generator.AutoGenerator;
    import com.baomidou.mybatisplus.generator.InjectionConfig;
    import com.baomidou.mybatisplus.generator.config.DataSourceConfig;
    import com.baomidou.mybatisplus.generator.config.FileOutConfig;
    import com.baomidou.mybatisplus.generator.config.GlobalConfig;
    import com.baomidou.mybatisplus.generator.config.PackageConfig;
    import com.baomidou.mybatisplus.generator.config.StrategyConfig;
    import com.baomidou.mybatisplus.generator.config.TemplateConfig;
    import com.baomidou.mybatisplus.generator.config.po.TableFill;
    import com.baomidou.mybatisplus.generator.config.po.TableInfo;
    import com.baomidou.mybatisplus.generator.config.rules.NamingStrategy;
    import com.baomidou.mybatisplus.generator.engine.FreemarkerTemplateEngine;
    
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.List;
    import java.util.Map;
    import java.util.Scanner;
    
    /** * @author evanYang * @version 1.0 * @date 09/25/2019 12:17 */
    public class CodeGenerator { 
    
        public static void main(String[] args) { 
    
            String packageName = "com.evan.springboot.tpi";   // 生成的包名
            boolean serviceNameStartWithI = false;//user -> UserService, 设置成true: user -> IUserService
    
            String dir = "D:\\IdeaProject\\springboot\\src\\main\\java";
            generateByTables(serviceNameStartWithI,
                    packageName,
                    dir, ""
            );
        }
        private static void generateByTables(boolean serviceNameStartWithI, String packageName, String dir, String... tableNames ) { 
            GlobalConfig globalConfig = new GlobalConfig();
            //mysql
            //String dbUrl = "jdbc:mysql://127.0.0.1:3306/test?serverTimezone=CTT&useUnicode=true&characterEncoding=utf-8&allowMultiQueries=true";
            //DataSourceConfig dataSourceConfig = new DataSourceConfig();
            //dataSourceConfig.setDbType(DbType.MYSQL)
            // .setUrl(dbUrl)
            // .setUsername("root")
            // .setPassword("root")
            // .setDriverName("com.mysql.cj.jdbc.Driver");
            String dbUrl = "jdbc:mysql://119.23.57.4:3306/okya?serverTimezone=CTT&useUnicode=true&characterEncoding=utf-8&allowMultiQueries=true";
            DataSourceConfig dataSourceConfig = new DataSourceConfig();
            dataSourceConfig.setDbType(DbType.MYSQL)
                    .setUrl(dbUrl)
                    .setUsername("okya")
                    .setPassword("SiKe!2#4%6")
                    .setDriverName("com.mysql.cj.jdbc.Driver");
    
            // 策略配置
            StrategyConfig strategyConfig = new StrategyConfig();
             //strategyConfig.setInclude("okya_version_manage");//"表名，多个英文逗号分割".split(",")
            strategyConfig
                    .setCapitalMode(false)   // 全局大写命名
                    .setEntityLombokModel(true)   // Lomnok
                    // .setDbColumnUnderline(true) // 表名 字段名 是否使用下滑线命名
                    .setTablePrefix("okya_") // 去除表前缀
                    .setRestControllerStyle(true)
                    .setNaming(NamingStrategy.underline_to_camel) underline_to_camel数据库表映射到实体的命名策略
                    //设置父类路径
                    .setSuperMapperClass("com.baomidou.mybatisplus.core.mapper.BaseMapper")
                    .setSuperServiceClass("com.baomidou.mybatisplus.extension.service.IService")
                    .setSuperServiceImplClass("com.baomidou.mybatisplus.extension.service.impl.ServiceImpl");
            //.setSuperEntityClass("com.baomidou.mybatisplus.extension.activerecord.Model");
    
    
            // 全局配置
            globalConfig.setActiveRecord(true)   //是否支持AR模式
                    .setAuthor("EvanYang")   // 设置作者
                    .setOutputDir(dir)   // 设置生成的目标路径（绝对路径）
                    .setIdType(IdType.UUID) //主键策略
                    .setBaseColumnList(true)  // 设置sql片段
                    .setBaseResultMap(true)  // resultMap
                    .setEnableCache(false)   // 不开缓存
                    .setMapperName("%sDao")
                    .setXmlName("%sMapper")
                    .setEntityName("%sModel")
                    .setOpen(false) //生成之后 默认打开文件夹
                    .setSwagger2(true)
                    .setFileOverride(true);  // 每一次生成需要覆盖
            if (!serviceNameStartWithI) { 
                globalConfig.setServiceName("I%sProvider");
                globalConfig.setServiceImplName("%sProvider");
            }
            //代码生成器
            new AutoGenerator().setGlobalConfig(globalConfig)
                    .setDataSource(dataSourceConfig)
                    .setStrategy(strategyConfig)
                    .setPackageInfo(
                            new PackageConfig()
                                    .setParent(packageName)
                                    .setController("controller")
                                    .setEntity("model")
                    ).execute();
        }
    
        private void generateByTables(String packageName, String dir,String... tableNames) { 
            generateByTables(true, packageName, dir, tableNames);
        }
    
    }

# 7 gitlub 上的代码地址 #

代码地址：[https://github.com/ylw530788697/springbootmybatisplus.git][https_github.com_ylw530788697_springbootmybatisplus.git]

[20200903162926348.png_pic_center]: /images/20221123/9d998dd9fa534edc93400a102334b955.png
[https_swagger.io]: https://swagger.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/a7bd09d3645f4208a069044d64b4bf9c.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221123/86508abca1aa44b19742647be2150460.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221123/2763e38236d74342b9face6cc16f5cac.png
[20200830145613194.png_pic_center]: /images/20221123/e5c1fb0e958c47e39fe63fd6fab928c5.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20221123/3b2261fcccc84e369697c65d089038c0.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zMDQwOTkyNw_size_16_color_FFFFFF_t_70_pic_center 4]: /images/20221123/23c0cf2e4ae6405d81a7b8f32fa5d210.png
[https_github.com_ylw530788697_springbootmybatisplus.git]: https://github.com/ylw530788697/springbootmybatisplus.git