Swagger2——常用注解复习总结

Swagger-UI

Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。

1、常用注解

• @Api：用于修饰Controller类，生成Controller相关文档信息

• @ApiModel()用于类 ；对类进行说明，表示一个返回响应数据的信息
  value–表示对象名
  description–描述

• @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

• @ApiOperation() 用于方法；表示一个http请求的操作 ;通常修饰Controller类中的方法，生成接口方法相关文档信息
  value用于方法描述
  notes用于提示内容
  tags可以重新分组s

• @ApiParam() 用于修饰接口中的参数，生成接口参数相关文档信息（说明或是否必填等）；
  name–参数名
  value–参数说明
  required–是否必填

• @ApiImplicitParams()用在请求的方法上，表示一组参数说明，包含多个 @ApiImplicitParam

• @ApiImplicitParam() 用于方法 ；表示单独的请求参数

  name–参数ming
  value–参数说明
  dataType–数据类型
  paramType–参数类型
  example–举例说明

• @ApiResponses：用在请求的方法上，表示一组响应

  @ApiResponse：用在@ApiResponses中，响应信息

  ​ code：数字，例如400

  ​ message：信息

示例

@ApiOperation("查询测试")
@GetMapping("select")
@ApiImplicitParams({ 
    @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="hello"), 	   @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")
}) 
public void select(String name,long id){ }

2、整合Swagger-UI

添加项目依赖：在pom.xml中新增Swagger-UI相关依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.6.0</version>
</dependency>

3、添加Swagger-UI的配置

添加Swagger-UI的Java配置文件,Swagger对生成API文档的范围有三种不同的选择:

• 生成指定包下面的类的API文档
• 生成有指定注解的类的API文档
• 生成有指定注解的方法的API文档

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.woniuxy.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())  //对所有路径进行监控
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("demo")
                .contact("admin")
                .version("1.0")
                .build();
    }
}

访问Swagger-UI接口文档地址

接口地址：http://localhost:8080/swagger-ui.html

在Spring Boot中使用swagger-bootstrap-ui

swagger-bootstrap-ui是基于swagger接口api实现的一套UI,因swagger原生ui是上下结构的，在浏览接口时不是很清晰,所以，swagger-bootstrap-ui是基于左右菜单风格的方式,方便浏览。

GitHub: https://github.com/xiaoymin/Swagger-Bootstrap-UI

<!--引入ui包-->
<dependency>
 <groupId>com.github.xiaoymin</groupId>
 <artifactId>swagger-bootstrap-ui</artifactId>
 <version>1.9.6</version>
</dependency>

配置类添加注解：

@EnableSwaggerBootstrapUI

basic认证

swagger:
  production: false
  basic:
    enable: true
    username: test
    password: 123

接口访问

在浏览器输入：http://${host}:${port}/doc.html

swagger-bootstrap-ui 指南

https://www.bookstack.cn/read/swagger-bootstrap-ui/quickstart.md