Swagger实现OpenAPI规范的工具集步骤详述

官网： https://swagger.io/
#################################################################

:）Swagger包含的工具集

1.Swagger编辑器：Swagger Editor允许您在浏览器中编辑YAML中的OpenAPI规范并实时预览文档。
2.Swagger UI： Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档。
3.Swagger Codegen：允许根据OpenAPI规范自动生成API客户端库（SDK生成），服务器存根和文档。
4.Swagger Parser：用于解析来自Java的OpenAPI定义的独立库
5.Swagger Core：与Java相关的库，用于创建，使用和使用OpenAPI定义
6.Swagger Inspector（免费）： API测试工具，可让您验证您的API并从现有API生成OpenAPI定义

#####################################################################

首先阐述说明一下：SpringBoot已经集成了Swagger，使用简单注解即可生成swagger的API文档

1）引入依赖

  引入依赖：在自己的pom.xml文件中进行添加

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>（版本信息自己根据公司情况进行编辑）</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>（版本信息自己根据公司情况进行编辑）</version>
</dependency>

#####################################################################

2）编写配置

编写配置信息：

@Configuration//@Configuration用于定义配置类，可替换xml配置文件，详情可以自己进行百度查询
@EnableSwagger2//启动Swagger2
public class SwaggerConfig {
   @Bean
   public Docket api() {
       return new Docket(DocumentationType.SWAGGER_2)
               .host("根URL链接地址")
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("项目controller类路径"))
               .paths(PathSelectors.any())
               .build();
   }

   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("XX项目系统")
               .description("XX项目系统接口文档")
               .version("XX项目版本号")
               .build();
   }
}

#################################################################

3）示例接口声明

   接口声明示例,在controller的每个handler上添加接口说明注解,
   注：以下示例，仅作Swagger文档编辑参考，无开发意义！

@RestController
@RequestMapping("xxx")
@Api("xxx服务接口")
public class Controller {

    @Autowired
    private XxxService xxxService;

    @Autowired
    private PayHelper payHelper;

     /**
     * 示例1：
     */
    @PostMapping("xxx")
    @ApiOperation(value = "XX接口", notes = "XX注释解释的解释说明")
    @ApiImplicitParam(name = "xxx", required = true, value = "对返回值解释")
    public ResponseEntity<Long> createOrder(@RequestBody @Valid Xxx xxx) {
        Long id = this.orderService.createXxx(xxx);
        return new ResponseEntity<>(id, HttpStatus.CREATED);
    }

    /**
     * 示例2：分页查询 
     *
     * @param status  状态
     * @return 分页数据
     */
    @GetMapping("list")
    @ApiOperation(value = "XX接口,及功能作用", 
                  notes = "XX注释解释的解释说明")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "page", value = "当前页",defaultValue = "1", type = "Integer"),
         //参数的解释和默认值类型及默认值
        @ApiImplicitParam(name = "rows", value = "页大小",defaultValue = "6", type = "Integer"), 
        //参数的解释和默认值类型及默认值
        @ApiImplicitParam(name = "status",value = "状态", type = "Integer"),
        //参数的解释和默认值类型
    })
    public ResponseEntity<PageResult<Xxx>> queryList(
        @RequestParam(value = "page", defaultValue = "1") Integer page,
        @RequestParam(value = "rows", defaultValue = "6") Integer rows,
        @RequestParam(value = "status", required = false) Integer status) {
        PageResult<Xxx> result = this.XXXService.queryList(page, rows, status);
        if (result == null) {
            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
        }
        return ResponseEntity.ok(result);
    }
}

4）启动测试

启动服务
1，进行访问：http://localhost:port/swagger-ui.html
2，点击order-controller，查看接口信息
3，点击任意一个接口，即可看到详细信息
附』常用注解说明

/**
 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数
 */

                                            !祝君学有所成，日入斗金！