如何搭建 Swagger API文档平台

相信大家平时开发的过程中，都会使用到 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 依赖中复制io.springfox 。

springfox-boot-starter 3.0.0 添加

复制springfox-boot-starter 依赖后，复制spring boot 能启动配置功能，配置好 复制swagger，所以我们不需要手动添加注解来启用 复制Swagger我们启动一下项目访问 。

复制Swagger 文档的 复制JSON API , 来看看 复制Springfox 是否正常运行我们可以在浏览器中输入以下URL：复制http://localhost:8080/v3/api-docs 。

能够看到以上的类似结果，说明我们第一步已经成功了第二步：将 复制Swagger 2 集成到 复制Spring Boot 项目中去我们创建一个 复制SwaggerConfig 类，并用 复制@Configura。

tion 注解来注释复制Swagger 的配置主要围绕着 复制Docket 对象来完成我们可以在 复制SwaggerConfig 类中添加以下代码复制@ConfigurationpublicclassSwaggerConfiguration

{ private ApiInfo apiInfo() { returnnew ApiInfo("Blog REST APIs", "REST APIs f

or Blog Application", "1.0", "Terms of service", new Cont

act("xxx", "xxx", "xxx"), "License of API", "API license URL", Collections.emptyList()); }

@Beanpublic Docket api() { returnnew Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandle

rSelectors.any()) .paths(PathSelectors.any()) .build(); } } 在构造 复制

Docket 对象之后，它的 复制select() 方法返回了 复制ApiSelectorBuilder 的一个实例，它提供了一种控制 复制Swagger 所暴露的端点的方法我们可以通过使用 复制RequestHandlerSelectors。

和 复制PathSelectors 配置选择 复制RequestHandlers 的路径如果两者两者使用 复制any() ， 那就说明配置所有的 API 都能在 复制Swagger 上显示了第三步：访问 。

复制Swagger UI复制Swagger UI 是一个内置的解决方案，使用户与 复制Swagger 生成的API文档的交互变得更加容易我们在浏览器中输入下面URL即可查看：复制http://localhost:8080/swagger-ui/。

结果应该是这样的好，到这里 复制Swagger 的使用配置就算结束了那接下来我们来看看怎么用JWT增加权限配置呢？配置 复制JWT复制JWT 是什么？相信大家都一定听过吧，它就是 复制JSON Web Token。

的缩写话不多说，直接上手代码配置起来在 复制SwaggerConfig 里面新增代码我们先来配置 复制ApiKey 作为 复制JWT 的认证复制header信息：复制publicstatic final 。

String AUTHORIZATION_HEADER = "Authorization"; private ApiKey apiKey(){ returnnew ApiKey(

"JWT", AUTHORIZATION_HEADER, "header"); } 下一步，我们配置 复制JWT 的 复制SecurityContext ， 对 复制SecurityContext

配置全局的 复制AuthorizationScope :复制private SecurityContext securityContext(){ return SecurityContext.builder().securityReferences(defaultAuth()).build(); }

private List defaultAuth(){ AuthorizationScope authorizationScope = new AuthorizationScope(

"global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[

1]; authorizationScopes[0] = authorizationScope; return Arrays.asList(new SecurityReference(

"JWT", authorizationScopes)); } 然后我们配置 复制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(); } 到这里，复制JWT 就配置完成了，感觉是不是挺简单的？好，我们再来运行一下，看看效果

我们点击右上角的 复制Authorize 按钮，弹出一个输入 复制apiKey 的弹出层。

输入 复制api key 之后，点击 复制Authorize 认证通过，我们就又能调用 API 接口调试了用注解定制 复制Swagger API 文档为了能够定制 复制Swagger 文档，复制swagger-core。

提供了一套注解来声明和操作输出复制Swagger-core 注解:NameDescription@Api标记为 Swagger 资源@ApiModel标记为 Swagger 模型@ApiModelProperty。

模型字段的属性说明@ApiOperationhttp接口的说明@ApiParamhttp 接口参数说明更多详细的说明可以参考 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 ){ ... } } 再来看看 复制@ApiModel 和

复制@ApiModelProperty 怎么使用：复制@ApiModel(description = "Post model information") @Data public class PostDto {

@ApiModelProperty(value = "Blog post id") private long id; } 是不是感觉 so easy？总结通过这篇文章我们学习了如何通过 复制Springfox

来搭建 复制Swagger API 文档平台，然后也学会了如何设置 复制JWT 的方式做认证，保证 复制API 不会被别人能够恶意使用。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。