阿里自助建站平台,有专门做dnf工作室的网站么,网页源代码快捷键,小红书关键词热度查询使用Swagger生成Web API文档
高质量的API文档在系统开发的过程中非常重要。本节介绍什么是Swagger#xff0c;如何在Spring Boot项目中集成Swagger构建RESTful API文档#xff0c;以及为Swagger配置Token等通用参数。
1.什么是Swagger
Swagger是一个规范和完整的框架…使用Swagger生成Web API文档
高质量的API文档在系统开发的过程中非常重要。本节介绍什么是Swagger如何在Spring Boot项目中集成Swagger构建RESTful API文档以及为Swagger配置Token等通用参数。
1.什么是Swagger
Swagger是一个规范和完整的框架用于生成、描述、调用和可视化RESTful风格的Web服务是非常流行的API表达工具。
普通的API文档存在以下问题
1由于接口众多并且细节复杂需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等创建这样一份高质量的文档是一件非常烦琐的工作。
2随着需求的不断变化接口文档必须同步修改就很容易出现文档和业务不一致的情况。为了解决这些问题Swagger应运而生它能够自动生成完善的RESTful API文档并根据后台代码的修改同步更新。这样既可以减少维护接口文档的工作量又能将说明内容集成到实现代码中让维护文档和修改代码合为一体实现代码逻辑与说明文档的同步更新。另外Swagger也提供了完整的测试页面来调试API让API测试变得轻松、简单。
2.使用Swagger生成Web API文档
在Spring Boot项目中集成Swagger同样非常简单只需在项目中引入springfox-swagger2和springfox-swagger-ui依赖即可。下面就以之前的用户管理模块接口为例来感受Swagger的魅力。
步骤01 配置Swagger的依赖。 dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion3.0.0/version/dependencydependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion3.0.0/version/dependency
在上面的示例中在项目pom.xml配置文件中引入了springfox-swagger2和springfox-swagger-ui两个依赖包。其中swagger2是主要的文档生成组件swagger-ui为页面显示组件。
步骤02 创建Swagger2配置类。
Configuration
EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {Beanpublic Docket createRestApi () {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage(com.example.demo.controller)).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(Spring boot中使用Swagger2构建RESTful APIs).description(相关文章请关注:https://blog.csdn.net/weixin_45627039?spm1000.2115.3001.5343).termsOfServiceUrl(https://blog.csdn.net/weixin_45627039?spm1000.2115.3001.5343)// .contact(架构师精进).version(1.0).build();}/*** swagger增加url映射* param registry*/Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler(swagger-ui.html).addResourceLocations(classpath:/META-INF/resources/);registry.addResourceHandler(/webjars/**).addResourceLocations(classpath:/META-INF/resources/webjars);}
}在上面的示例中我们在SwaggerConfig的类上添加了Configuration和EnableSwagger2两个注解。
Configuration注解让Spring Boot来加载该类配置。
EnableSwagger2注解启用Swagger2通过配置一个Docket Bean来配置映射路径和要扫描的接口所在的位置。
apiInfo主要配置Swagger2文档网站的信息比如网站的标题、网站的描述、使用的协议等。
需要注意的是
1basePackage可以在SwaggerConfig中配置com.weiz.example01.controller也可以在启动器ComponentScan中配置。
2需要在SwaggerConfig中配置Swagger的URL映射地址/swagger-ui.html。
步骤03 添加文档说明内容。
上面的配置完成之后接下来需要在API上增加内容说明。我们直接在之前的用户管理模块的UserController中增加相应的接口内容说明代码如下 Api(tags {用户接口})RestControllerpublic class UserController {ApiOperation(value创建用户, notes根据User对象创建用户)PostMapping(value user)public JSONResult save(RequestBody User user){System.out.println(用户创建成功: user.getName());return JSONResult.ok(201, 用户创建成功);}ApiOperation(value更新用户详细信息, notes根据id来指定更新对象并根据传过来的user信息来更新用户详细信息)PutMapping(value user)public JSONResult update(RequestBody User user) {System.out.println(用户修改成功: user.getName());return JSONResult.ok(203, 用户修改成功);}ApiOperation(value删除用户, notes根据url的id来指定删除对象)ApiImplicitParam(name userId, value 用户ID, required true, dataType Long, paramType query)DeleteMapping(user/{userId})public JSONResult delete(PathVariable String userId) {System.out.println(用户删除成功: userId);return JSONResult.ok(204,用户删除成功);}}在上面的示例中主要为UserController中的接口增加了接口信息描述包括接口的用途、请求参数说明等。
1Api注解用来给整个控制器Controller增加说明。
2ApiOperation注解用来给各个API方法增加说明。
3ApiImplicitParams、ApiImplicitParam注解用来给参数增加说明。
步骤04 查看生成的API文档。
完成上面的配置和代码修改之后Swagger 2就集成到Spring Boot项目中了。接下来启动项目在浏览器中访问http://localhost:8080/swagger-ui.htmlSwagger会自动构建接口说明文档如图所示。 Swagger自动将用户管理模块的全部接口信息展现出来包括接口功能说明、调用方式、请求参数、返回数据结构等信息。
在Swagger页面上我们发现每个接口描述右侧都有一个按钮try it out单击try it out按钮即可调用该接口进行测试。如图所示在获取人员信息的接口上单击try it out按钮输入userId的请求参数“2001”单击Execute按钮就会将请求发送到后台从而进行接口验证测试。 3.为Swagger添加token参数
很多时候客户端在调用API时需要在HTTP的请求头携带通用参数比如权限验证的token参数等。但是Swagger是怎么描述此类参数的呢接下来通过示例演示如何为Swagger添加固定的请求参数。
其实非常简单修改Swagger2Config配置类利用ParameterBuilder构成请求参数。具体示例代码如下
Configuration
EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {Beanpublic Docket createRestApi() {ParameterBuilder parameterBuilder new ParameterBuilder();ListParameter parameters new ArrayListParameter();parameterBuilder.name(token).description(token令牌).modelRef(new ModelRef(string)).parameterType(header).required(false).build();return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage(com.example.demo.controller)).paths(PathSelectors.any()).build().globalOperationParameters(parameters);}...
}在上面的示例中通过ParameterBuilder类把token作为全局统一的参数添加到HTTP的请求头中。系统所有的API都会统一加上此参数。
完成之后重新启动应用再次查看接口如图所示我们可以看到接口参数中已经支持发送token请求参数。 人员管理模块中的所有API都统一加上了token参数调用时Swagger会将token参数自动加入HTTP的请求头。
4.Swagger常用注解
Swagger提供了一系列注解来描述接口信息包括接口说明、请求方法、请求参数、返回信息等常用注解如表所示。 在实际项目中Swagger除了提供ApiImplicitParams注解描述简单的参数之外还提供了用于对象参数的ApiModel和ApiModelProperty两个注解用于封装的对象作为传入参数或返回数据。
ApiModel负责描述对象的信息
ApiModelProperty负责描述对象中属性的相关内容
以上是在项目中常用的一些注解利用这些注解就可以构建出清晰的API文档。
