c语言sscanf函数的用法是什么
291
2023-05-22
三步轻松集成Swagger API文档
本文转载自微信公众号「Java技术指北」，作者指北君 。转载本文请联系Java技术指北公众号。
大家好， 我是指北君。
相信大家平时开发的过程中，都会使用到 API文档工具吧?大家都在使用什么呀?Java docs，I/O Docs, apiary.io, Docco, Dexy, Doxygen, TurnAPI，Swagger。今天我就来教大家如何使用 Swagger 搭建 API 文档，并且配置权限使用。毕竟开发文档还是内容使用的为好，万一上线到生产环境，没有关swagger 又没有设置权限，那可不GG啦。
好，我们这就上手搞起来。
我们将使用 Springfox 对 Swagger 2 规范的实现，并通过 JWT 的方式来设置权限。
配置SwaggerUI
第一步：向Spring Boot项目添加Maven依赖项
打开 pom.xml 文件，添加 springfox-boot-starter 到 maven 依赖中。
复制<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
1.2.3.4.5.
添加 springfox-boot-starter 依赖后，spring boot 能启动配置功能，配置好 swagger，所以我们不需要手动添加注解来启用 Swagger。
我们启动一下项目访问 Swagger 文档的 JSON API , 来看看 Springfox 是否正常运行。我们可以在浏览器中输入以下URL：
复制http://localhost:8080/v3/api-docs
1.
能够看到以上的类似结果，说明我们第一步已经成功了。
第二步：将 Swagger 2 集成到 Spring Boot项目中去
我们创建一个 SwaggerConfig 类，并用 @Configuration 注解来注释。Swagger 的配置主要围绕着 Docket 对象来完成。我们可以在 SwaggerConfig 类中添加以下代码。
复制@Configuration
public class SwaggerConfiguration {
private ApiInfo apiInfo() {
return new ApiInfo("Blog REST APIs",
"REST APIs for Blog Application",
"1.0",
"Terms of service",
new Contact("xxx", "xxx", "xxx"),
"License of API",
"API license URL",
Collections.emptyList());
}
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.
在构造 Docket 对象之后，它的 select() 方法返回了 ApiSelectorBuilder 的一个实例，它提供了一种控制 Swagger 所暴露的端点的方法。
我们可以通过使用 RequestHandlerSelectors 和 PathSelectors 配置选择 RequestHandlers 的路径。如果两者两者使用 any() ， 那就说明配置所有的 API 都能在 Swagger 上显示了。
第三步：访问 Swagger UI
Swagger UI 是一个内置的解决方案，使用户与Swagger 生成的API文档的交互变得更加容易。我们在浏览器中输入下面URL即可查看：
复制http://localhost:8080/swagger-ui/
1.
结果应该是这样的。
好，到这里 Swagger 的使用配置就算结束了。那接下来我们来看看怎么用JWT增加权限配置呢?
配置 JWT
JWT 是什么?相信大家都一定听过吧，它就是 JSON Web Token 的缩写。话不多说，直接上手代码配置起来。在 SwaggerConfig 里面新增代码。
我们先来配置 ApiKey 作为 JWT 的认证 header信息：
复制 public static final String AUTHORIZATION_HEADER = "Authorization";
private ApiKey apiKey(){
return new ApiKey("JWT", AUTHORIZATION_HEADER, "header");
}
1.2.3.4.
下一步，我们配置 JWT 的 SecurityContext ， 对 SecurityContext 配置全局的 AuthorizationScope :
复制 private SecurityContext securityContext(){
return SecurityContext.builder().securityReferences(defaultAuth()).build();
}
private List<SecurityReference> defaultAuth(){
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}
1.2.3.4.5.6.7.8.9.
然后我们配置 Docket 对象，对 Docket 对象设置 SecurityContext ，SecuritySchemes。
复制 @Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.securityContexts(Arrays.asList(securityContext()))
.securitySchemes(Arrays.asList(apiKey()))
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
1.2.3.4.5.6.7.8.9.10.11.
到这里，JWT 就配置完成了，感觉是不是挺简单的?好，我们再来运行一下，看看效果
我们点击右上角的 Authorize 按钮，弹出一个输入 apiKey 的弹出层。
输入 api key 之后，点击 Authorize 认证通过，我们就又能调用 API 接口调试了。
用注解定制 Swagger API 文档
为了能够定制 Swagger 文档，swagger-core 提供了一套注解来声明和操作输出。
Swagger-core 注解:
Name
Description
@Api
标记为 Swagger 资源
@ApiModel
标记为 Swagger 模型
@ApiModelProperty
模型字段的属性说明
@ApiOperation
http接口的说明
@ApiParam
http 接口参数说明
更多详细的说明可以参考 GitHub 上的解释：https://github.com/swagger-api/swagger-core/wiki/annotations
现在我们就举个例子来解释怎么使用这些个注解， 首先来看 @Api 和 @ApiOperation 怎么使用：
复制@Api(value = "CRUD Rest APIs for Post resources")
@RestController
@RequestMapping()
public class PostController {
@ApiOperation(value = "Get All Posts REST API")
@GetMapping("/api/v1/posts")
public PostResponse getAllPosts(
@RequestParam(value = "pageNo", defaultValue = "0", required = false) int pageNo,
@RequestParam(value = "pageSize", defaultValue = "100", required = false) int pageSize
){
...
}
}
1.2.3.4.5.6.7.8.9.10.11.12.13.14.
再来看看 @ApiModel 和 @ApiModelProperty 怎么使用：
复制@ApiModel(description = "Post model information")
@Data
public class PostDto {
@ApiModelProperty(value = "Blog post id")
private long id;
}
1.2.3.4.5.6.
是不是感觉 so easy?
总结
通过这篇文章我们学习了如何通过 Springfox 来搭建 Swagger API 文档平台，然后也学会了如何设置 JWT 的方式做认证，保证 API 不会被别人能够恶意使用。
版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。
相关文章
发表评论
暂时没有评论，来抢沙发吧~