本文转载自微信公众号《Java技术指南北》，作者指北军转载请联系Java技术指南公众号。大家好，我是北军。相信大家在平时的开发过程中都会用到API文档工具吧？你在用什么？Java文档、I/O文档、apiary.io、Docco、Dexy、Doxygen、TurnAPI、Swagger。今天教大家如何使用Swagger构建API文档和配置权限。毕竟还是用开发文档的内容比较好。如果上线到生产环境，没有关闭swagger，也没有设置权限，那就不是GG了。好的，让我们开始吧。我们将使用Springfox对Swagger2规范的实现，并通过JWT设置权限。配置SwaggerUI第一步：在SpringBoot项目中添加Maven依赖打开pom.xml文件，在maven依赖中添加springfox-boot-starter。io.springfoxspringfox-boot-starter3.0.0添加springfox-boot-starter依赖后，springboot它可以启动配置功能和配置swagger，所以我们不需要手动添加注解来启用swagger。下面我们启动项目访问Swagger文档的JSONAPI，看看Springfox是否正常运行。我们可以在浏览器中输入如下网址：http://localhost:8080/v3/api-docs可以看到和上面类似的结果，说明我们第一步已经成功了。第二步：将Swagger2集成到SpringBoot项目中。我们创建一个SwaggerConfig类并使用@Configuration注释对其进行注释。Swagger的配置主要是围绕Docket对象进行的。我们可以在SwaggerConfig类中添加如下代码。@ConfigurationpublicclassSwaggerConfiguration{privateApiInfoapiInfo(){returnnewApiInfo("博客RESTAPIs","博客应用程序的RESTAPIs","1.0","服务条款",newContact("xxx","xxx","xxx"),"API许可证","API许可证URL",Collections.emptyList());}@BeanpublicDocketapi(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();}}构造完Docket对象后，它的select()方法返回一个ApiSelectorBuilder的实例，它提供了一种控制Swagger暴露的端点的方法。我们可以使用RequestHandlerSelectors和PathSelectors配置为RequestHandlers选择路径。如果两者都使用any()，则意味着配置的所有API都可以在Swagger上显示。第3步：访问SwaggerUISwaggerUI是一种内置解决方案，使用户可以更轻松地与Swagger生成的API文档进行交互。我们可以在浏览器中输入以下网址来查看：http://localhost:8080/swagger-ui/结果应该是这样的。好了，Swagger的使用配置到这里就结束了。那我们来看看如何使用JWT来添加权限配置？什么是JWT配置？相信大家一定听说过，它是JSONWebToken的缩写。话不多说，直接上手代码配置。在SwaggerConfig中添加代码。我们先配置ApiKey作为JWT的认证头信息：publicstaticfinalStringAUTHORIZATION_HEADER="Authorization";privateApiKeyapiKey(){returnnewApiKey("JWT",AUTHORIZATION_HEADER,"header");接下来，我们配置JWTSecurityContext，为SecurityContext配置全局的AuthorizationScope：}privateListdefaultAuth()(AuthorizationScope=newAuthorizationScopeauthorization"global","accessEverything");AuthorizationScope[]authorizationScopes=newAuthorizationScope[1];authorizationScopes[0]=authorizationScope;返回Arrays.asList(newSecurityReference("JWT",authorizationScopes));然后我们配置Docket对象，为Docket对象设置SecurityContext、SecuritySchemes。@BeanpublicDocketapi(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).securityContexts(Arrays.asList(securityContext())).securitySchemes(Arrays.asList(apiKey())).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();至此，JWT配置完成。是不是很简单？好了，我们再运行一??下，看看效果我们点击右上角的Authorize按钮，弹出一个输入apiKey的弹层。输入apikey后，点击Authorize认证通过，我们就可以再次调用API接口进行调试了。使用注释自定义SwaggerAPI文档为了能够自定义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="CRUDRestAPIsforPostresources")@RestController@RequestMapping()publicclassPostController{@ApiOperation(value="GetAllPostsRESTAPI")@GetMapping("/api/v1/posts")publicPostResponsegetAllPosts(@RequestParam(value="pageNo",defaultValue="0",required=false)intpageNo,@RequestParam(value="pageSize",defaultValue="100",required=false)intpageSize){...}}让我们看看@ApiModel和如何使用@ApiModelProperty：@ApiModel(description="Postmodelinformation")@DatapublicclassPostDto{@ApiModelProperty(value="博文id")privatelongid;}是不是感觉这么简单？总结我们通过这篇文章学习如何通过Springfox构建SwaggerAP我文档平台，然后也学习了如何设置JWT进行认证，保证API不会被别人恶意使用
