SpringBoot+Swagger2实现自动生成API文档

深碍√TFBOYSˉ_ 2022-01-29 12:39 579阅读 0赞

## Swagger概述 ##

> Swagger是一组围绕OpenAPI规范构建的开源工具，可帮助设计、构建、记录和使用REST API。  
> 简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口  
> 修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。

## Swagger2 配置 ##

需要在你的SpringBoot工程中加入如下pom

<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常用注解 ##

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

*  @Api：修饰整个类，描述Controller的作用
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口
 *  @ApiParam：单个参数描述
 *  @ApiModel：用对象来接收参数
 *  @ApiProperty：用对象接收参数时，描述对象的一个字段
 *  @ApiResponse：HTTP响应其中1个描述
 *  @ApiResponses：HTTP响应整体描述
 *  @ApiIgnore：使用该注解忽略这个API
 *  @ApiError ：发生错误返回的信息
 *  @ApiParamImplicitL：一个请求参数
 *  @ApiParamsImplicit 多个请求参数  
    需要注意的时上述的参数注解在后续的版本中已经修改了，这个要引起注意

## Swagger错误java.lang.NoClassDefFoundError: io/swagger/models/Contact ##

这个错误我基本断定与Swagger版本和SpringBoot携带的Spring版本有关，上述Swagger2.4.0的无法与SpringBoot2版本配合使用，因此在我们后续的使用中需要注意版本的配合关系