springboot整合swagger

朱雀 2020-10-18 12:20 1172阅读 0赞

### swagger ###

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，  
对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。  
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。  
文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

### springboot + swagger ###

现在pom文件中添加swagger依赖

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

接下来就是对swagger进行配置

@Configuration
    @EnableSwagger2
    public class SwaggerUtil {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //.apis(RequestHandlerSelectors.basePackage("com.iresearch.cms.controller"))
                    //这个是扫描有Api注解的类
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("springboot利用swagger构建api文档")
                    .description("简单优雅的restfun风格，http://blog.csdn.net/saytime")
                    .termsOfServiceUrl("http://blog.csdn.net/saytime")
                    .version("1.0")
                    .build();
        }
    }

其中 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 这块是重点，主要扫描有@Api注解的类，也可以使用  .apis(RequestHandlerSelectors.basePackage("com.iresearch.cms.controller")) 这个代码，这个是指定哪个包。

接下来就是在controller中使用了

最后就是要在启动类中添加@EnableSwagger2这个注解，表示开启swagger

运行项目之后，访问 [http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

swagger注解

*  @Api：描述controller
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口
 *  @ApiParam：单个参数描述
 *  @ApiModel：用对象来接收参数
 *  @ApiProperty：用对象接收参数时，描述对象的一个字段
 *  @ApiResponse：HTTP响应其中1个描述
 *  @ApiResponses：HTTP响应整体描述
 *  @ApiIgnore：使用该注解忽略这个API
 *  @ApiError ：发生错误返回的信息
 *  @ApiImplicitParam：一个请求参数
 *  @ApiImplicitParams：多个请求参数 例如：@ApiImplicitParams(\{@ApiImplicitParam(name = "username",value = "用户名",required = true,dataType = "String"),@ApiImplicitParam(name = "password",value = "密码",required = true,dataType = "String")\})

[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html#/