勐海县城乡建设局门户网站,网站制作 网站开发,想自己做一个网站,树枝seoSwagger的简单介绍
Swagger 是一个 RESTful 接口文档的规范和工具集#xff0c;它的目标是统一 RESTful 接口文档的格式和规范。在开发过程中#xff0c;接口文档是非常重要的一环#xff0c;它不仅方便开发者查看和理解接口的功能和参数#xff0c;还能帮助前后端开发协同…Swagger的简单介绍
Swagger 是一个 RESTful 接口文档的规范和工具集它的目标是统一 RESTful 接口文档的格式和规范。在开发过程中接口文档是非常重要的一环它不仅方便开发者查看和理解接口的功能和参数还能帮助前后端开发协同工作提高开发效率。在 Spring Boot 中我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口然后根据这些注解自动生成接口文档。
同类型的产品
ApiDoc
ApiDoc定位 ApiDocPostmanSwaggermockJmeter是一款集 API设计接口文档管理、代码生成、API 调试、API mock,API 自动化为一体的接口一站式协作平台。
也就是说它比 swagger 的的功能要更加广泛和齐全不仅通过可视化界面设计接口生成接口文档和项目代码
还打通了接口数据的协作流程一套接口数据设计出来可以给前端、测试使用减少了再不同系统间切换、导入导出数据、更新维护的麻烦。
缺点太繁琐因为支持了太多的功能并且也不符合注解式开发的规范需要写大量的文档类东西。
Swagger的简单上手
依赖
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version
/dependency
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version
/dependency配置
Swagger是通过配置类的方式来添加配置的
Configuration
EnableSwagger2
public class SwaggerConfig {Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage(com.example.demo.controller)).paths(PathSelectors.any()).build().apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(接口文档).description(接口文档).version(1.0.0).build();}
}注解
Api用于描述接口的类或接口ApiOperation用于描述接口的方法ApiParam用于描述接口的参数ApiModel用于描述数据模型ApiModelProperty用于描述数据模型的属性ApiImplicitParams方法参数的说明ApiImplicitParam用于指定单个参数的说明ApiResponses方法返回值的说明ApiResponse用于指定单个参数的说明
注解属性
valueurl的路径值tags 如果设置这个值、value的值会被覆盖description对api资源的描述basePath基本路径position如果配置多个Api 想改变显示的顺序位置produces “application/json, application/xml”consumes“application/json, application/xml”protocols http, https, ws, wss.authorizations 高级特性认证时配置hidden 配置为true 将在文档中隐藏
查看接口文档
启动 Spring Boot 应用后我们可以在浏览器中访问http://localhost:8080/swagger-ui.html来查看接口文档。在 Swagger UI 页面中我们可以看到所有的接口信息包括接口名称、请求方式、请求路径、请求参数、响应参数等。
Swagger的用法
1、描述数据模型
我们可以使用 ApiModel 和 ApiModelProperty 注解来描述数据模型和属性。例如我们可以编写一个 User 类并在类上使用 ApiModel 和
ApiModelProperty 注解来描述该数据模型ApiModel(description 用户信息)
public class User {ApiModelProperty(value 用户 ID, example 1) private Long id;ApiModelProperty(value 用户名, example 张三)private String username;ApiModelProperty(value 密码, example 123456)private String password;// 省略 getter 和 setter 方法
}在上面的代码中ApiModel 表示该类是一个数据模型ApiModelProperty 表示该属性是数据模型的一个属性value 属性表示属性的描述example 属性表示属性的示例值。
2、描述枚举类型
我们可以使用 ApiModel 和 ApiModelProperty 注解来描述枚举类型。例如我们可以编写一个 Gender 枚举类型并在枚举值上使用 ApiModelProperty 注解来描述该枚举值
ApiModel(description 性别) public enum Gender {ApiModelProperty(value 男)
MALE,ApiModelProperty(value 女)
FEMALE;
}在上面的代码中ApiModel 表示该枚举类型是一个描述性别的枚举类型ApiModelProperty 表示该枚举值是描述男性的枚举值或描述女性的枚举值。
3、描述响应参数
我们可以使用 ApiResponses 和 ApiResponse 注解来描述接口的响应参数。例如我们可以编写一个 getUserById() 方法并在方法上使用 ApiResponses 和 ApiResponse 注解来描述该方法的响应参数
GetMapping(/user/{id})
ApiOperation(value 根据 ID 获取用户信息)
ApiResponses({ ApiResponse(code 200, message 请求成功, response User.class),
ApiResponse(code 404, message 用户不存在) })
public User getUserById(ApiParam(value 用户 ID, required true) PathVariable Long id)
{ // 根据 ID 查询用户信息
}在上面的代码中ApiResponses 表示该方法的响应参数ApiResponse 表示该响应参数的描述code 属性表示响应码message 属性表示响应消息response 属性表示响应的数据模型。
五、Swagger 的进阶使用
1、配置全局参数
我们可以在配置类中使用 globalOperationParameters() 方法来配置全局参数。例如我们可以配置一个全局的 Authorization 参数用于授权
Configuration
EnableSwagger2
public class SwaggerConfig {Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage(com.example.demo.controller)).paths(PathSelectors.any()).build().globalOperationParameters(Arrays.asList(new ParameterBuilder().name(Authorization).description(授权).modelRef(new ModelRef(string)).parameterType(header).required(false).build())).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(接口文档).description(接口文档).version(1.0.0).build();}}在上面的代码中我们通过 globalOperationParameters() 方法来配置一个全局的 Authorization 参数用于授权。
2、配置安全协议
我们可以在配置类中使用 securitySchemes() 方法来配置安全协议。例如我们可以配置一个 Bearer Token 安全协议
Configuration
EnableSwagger2
public class SwaggerConfig {Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage(com.example.demo.controller)).paths(PathSelectors.any()).build().securitySchemes(Arrays.asList(new ApiKey(Bearer, Authorization, header))).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(接口文档).description(接口文档).version(1.0.0).build();}}在上面的代码中我们通过 securitySchemes() 方法来配置一个 Bearer Token 安全协议。
3、配置安全上下文
我们可以在配置类中使用 securityContexts() 方法来配置安全上下文。例如我们可以配置一个安全上下文用于在 Swagger UI 中显示认证按钮
Configuration
EnableSwagger2
public class SwaggerConfig {Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage(com.example.demo.controller)).paths(PathSelectors.any()).build().securitySchemes(Arrays.asList(new ApiKey(Bearer, Authorization, header))).securityContexts(Collections.singletonList(SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference(Bearer, new AuthorizationScope[0]))).build())).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(接口文档).description(接口文档).version(1.0.0).build();}}在上面的代码中我们通过 securityContexts() 方法来配置一个安全上下文用于在 Swagger UI 中显示认证按钮。
4、配置忽略参数
在接口中有些参数可能是敏感信息我们不希望在接口文档中显示。我们可以使用 ApiIgnore 注解来忽略这些参数。例如我们可以在 User 类中使用 ApiIgnore 注解来忽略密码参数
ApiModel(description 用户信息)
public class User {ApiModelProperty(value 用户 ID, example 1)private Long id;ApiModelProperty(value 用户名, example 张三)private String username;ApiModelProperty(hidden true)ApiIgnoreprivate String password;// 省略 getter 和 setter 方法
}在上面的代码中ApiModelProperty(hidden true) 表示该参数是隐藏的ApiIgnore 表示忽略该参数。
六、总结
通过集成 Swagger我们可以方便地生成接口文档使得前后端开发协同更加高效。在使用 Swagger 时我们需要注意以下几点
使用注解来描述接口信息包括接口名称、请求方式、请求路径、请求参数、响应参数等在配置类中配置 Swagger包括扫描的包路径、接口文档信息、全局参数、安全协议、安全上下文等描述数据模型、枚举类型、响应参数等信息方便开发者查看和理解接口的功能和参数在需要时使用 ApiIgnore 注解来忽略敏感参数的显示。最后需要注意的是Swagger 只是一种规范和工具集它并不能取代单元测试和集成测试等其他测试方式。在开发过程中我们需要综合使用各种测试方式保证软件的质量和稳定性。
