失眠网 > API接口文档利器：Swagger

API接口文档利器：Swagger

时间：2018-08-01 02:11:11

相关推荐

API接口文档利器：Swagger

文章目录

API接口文档利器：SwaggerSwagger介绍Swagger常用注解Swagger测试Swagger生成API文档的工作原理：

API接口文档利器：Swagger

Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

官网地址 :https://swagger.io/

它的主要作用是：

使得前后端分离开发更加方便，有利于团队协作接口的文档在线自动生成，降低后端开发人员编写接口文档的负担功能测试

Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入

Springfox ，即可非常简单快捷的使用Swagger

SpringBoot集成Swagger

在shanjupay-common项目中添加依赖，只需要在shanjupay-common中进行配置即可，因为其他微服务工

程都直接或间接依赖shanjupay-common。

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

\2. 在jspringboot工程的confifig包中添加一个Swagger配置类

package cn.yyl.sailing.config;import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")@EnableSwagger2public class SwaggerConfiguration {@Beanpublic Docket buildDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInfo()).select()// 要扫描的API(Controller)基础包.apis(RequestHandlerSelectors.basePackage("cn.itcast.sailing.controller")).paths(PathSelectors.any()).build();}/*** @param* @return springfox.documentation.service.ApiInfo* @Title: 构建API基本信息* @methodName: buildApiInfo*/private ApiInfo buildApiInfo() {Contact contact = new Contact("徐帆","","");return new ApiInfoBuilder().title("验证码服务API文档").description("包含验证码、短信api").contact(contact).version("1.0.0").build();}}

添加SpringMVC配置类：WebMvcConfifig，让外部可直接访问Swagger文档

package cn.yyl.sailing.config;import org.ponent;import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;@Componentpublic class WebMvcConfig implements WebMvcConfigurer {/*** 添加静态资源文件，外部可以直接访问地址** @param registry*/@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}

Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数的描述信息

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：

上边的属性后边编写程序时用到哪个我再详细讲解，下边写一个swagger的简单例子，我们在MerchantController 中添加Swagger注解，代码如下所示：

package cn.yyl.sailing.controller;import cn.mon.domain.RestResponse;import cn.itcast.sailing.dto.VerificationInfo;import cn.itcast.sailing.service.VerificationService;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.*;import java.util.Map;@Api(value = "验证码服务接口")@RestControllerpublic class VerificationController {@Autowiredprivate VerificationService verificationService;/*** 生成手机验证码** @param name业务名* @param payload 业务携带参数，如手机号，邮箱* @param effectiveTime 验证信息有效期(秒)* @return*/@ApiOperation(value = "生成验证信息", notes = "生成验证信息")@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "业务名称", required = true, dataType = "String", paramType = "query"),@ApiImplicitParam(name = "payload", value = "业务携带参数，如手机号，邮箱", required = true, paramType = "body"),@ApiImplicitParam(name = "effectiveTime", value = "验证信息有效期(秒)", required = false, dataType = "String", paramType = "query")})@PostMapping(value = "/generate")public RestResponse<VerificationInfo> generateVerificationInfo(@RequestParam("name") String name,@RequestBody Map<String, Object> payload,@RequestParam("effectiveTime") int effectiveTime) {VerificationInfo verificationInfo = verificationService.generateVerificationInfo(name, payload, effectiveTime);return RestResponse.success(verificationInfo);}/**** 校验手机验证码* @param name 业务名称* @param verificationKey 验证key* @param verificationCode 验证码* @return*/@ApiOperation(value = "校验", notes = "校验")@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "业务名称", required = true, dataType = "String", paramType = "query"),@ApiImplicitParam(name = "verificationKey", value = "验证key", required = true, dataType = "String", paramType = "query"),@ApiImplicitParam(name = "verificationCode", value = "验证码", required = true, dataType = "String", paramType = "query")})@PostMapping(value = "/verify")public RestResponse<Boolean> verify(String name, String verificationKey, String verificationCode) {Boolean isSuccess = verificationService.verify(name, verificationKey, verificationCode);return RestResponse.success(isSuccess);}@ApiOperation("测试")@GetMapping(path = "/hello")public String hello() {return "hello";}@ApiOperation("测试")@ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "string")@PostMapping(value = "/hi")public String hi(String name) {return "hi," + name;}}