Swagger是一组围绕OpenAPI规范构建的开源工具，可帮助设计、构建、记录和使用REST API。 简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口 修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。
需要在你的SpringBoot工程中加入如下pom
<!-- swagger2 配置 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency>在配置好pom文件之后，我们需要开启Swagger2,我们可以使用两种方式来实现。第一种直接在启动类上加入@EnableSwagger2注解，即可 第二种则是新建配置类来自定义一些Swagger2的属性，如下
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 @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() .apis(RequestHandlerSelectors.basePackage("com.imooc.controller")) .paths(PathSelectors.any()).build(); } /* * @Description: 构建 api文档的信息 */ private ApiInfo apiInfo() { return new ApiInfoBuilder() // //大标题 .title("测试系统 RESTful API") // 版本号 .version("2.0") // .termsOfServiceUrl("NO terms of service") // 描述 .description("API 描述") //作者 .contact(new Contact("zhao", "https://blog.csdn.net/u011342403", "1182867739@qq.com")) // .license("The Apache License, Version 2.0") // .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html") .build(); } }在我们的Controller和Model中加入一些Swagger2的注解配置
@RestController @Api(value="用户注册登录接口",tags="登录注册controller") public class RegistLoginController { @Autowired UserService userService; @PostMapping(value="/regist") @ApiOperation(value="用户注册",notes="注册接口") public IMoocJSONResult regist(@RequestBody Users users){ if (StringUtils.isBlank(users.getUsername())||StringUtils.isBlank(users.getPassword())) { return IMoocJSONResult.errorMsg("用户名或密码不能为空"); } if (userService.queryUsernameIsExist(users.getUsername())) { return IMoocJSONResult.errorMsg("该用户名已存在，请重新注册"); }else { userService.saveUser(users); } return IMoocJSONResult.ok(); } }Model配置
@ApiModel(value="用户对象",description="这是用户对象") public class Users { @Id @ApiModelProperty(hidden=true) private String id; /** * 用户名 */ @ApiModelProperty(value="用户名",name="username",example="imooc",required=true) private String username; /** * 密码 */ @ApiModelProperty(value="密码",name="password",example="123456",required=true) private String password; /** * 我的头像，如果没有默认给一张 */ @Column(name = "face_image") @ApiModelProperty(hidden=true) private String faceImage; /** * 昵称 */ private String nickname; /** * 我的粉丝数量 */ @Column(name = "fans_counts") @ApiModelProperty(hidden=true) private Integer fansCounts; /** * 我关注的人总数 */ @Column(name = "follow_counts") @ApiModelProperty(hidden=true) private Integer followCounts; /** * 我接受到的赞美/收藏 的数量 */ @Column(name = "receive_like_counts") @ApiModelProperty(hidden=true) private Integer receiveLikeCounts;使用上述注解可义定义在传入参数时，是否必须传入等属性 。
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用@ApiOperation：描述一个类的一个方法，或者说一个接口@ApiParam：单个参数描述@ApiModel：用对象来接收参数@ApiProperty：用对象接收参数时，描述对象的一个字段@ApiResponse：HTTP响应其中1个描述@ApiResponses：HTTP响应整体描述@ApiIgnore：使用该注解忽略这个API@ApiError ：发生错误返回的信息@ApiParamImplicitL：一个请求参数@ApiParamsImplicit 多个请求参数 需要注意的时上述的参数注解在后续的版本中已经修改了，这个要引起注意这个错误我基本断定与Swagger版本和SpringBoot携带的Spring版本有关，上述Swagger2.4.0的无法与SpringBoot2版本配合使用，因此在我们后续的使用中需要注意版本的配合关系
