4_生成 Swagger 接口文档

是什么

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specifification（OpenAPI 规范，也简称 OAS）。Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。 Swagger 是一种通用的，和编程语言无关的 API 描述规范

你可以用 Swagger-editor 来编写 API 文档（ yaml 文件 或 json文件），然后通过 Swagger-ui 来渲染该文件，以非常美观的形式将你的 API 文档，展现给你的团队或者客户

如果你的 RESTful API 接口都开发完成了，也可以使用 Swagger ，来设计和规范你的 API，以Annotation （注解）的方式给你的源代码添加额外的数据。这样，Swagger 就可以检测到这些数据，自动生成对应的 API 文档

---

怎么做

1、改pom

在 supergo_manager_web9001 中添加依赖

<!-- swagger：前端访问的服务,使用swagger生成相应的接口文档说明 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>

2、swagger 配置类

package com.supergo.config;
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;
/**
 * @Author: xj0927
 * @Description: Swagger 文档配置类
 * @Date Created in 2020-12-24 17:09
 * @Modified By: xj927
 */
@Configuration //注入Spring容器
@EnableSwagger2 //发现swagger
public class SwaggerConfig {

    @Bean
    public Docket groupRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(groupApiInfo())
                //配置分组
                .groupName("品牌组")
                // 通过.select()方法，去配置扫描接口
                .select()
                //配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.supergo.controller"))
                //筛选显示请求 URL
                .paths(PathSelectors.any())
                .build();
    }
    //Api文档信息
    private ApiInfo groupApiInfo() {
        //联系人方式
        Contact contact = new Contact("xj927", "www.baidu.com", "xxx@163.com");
        return new ApiInfoBuilder()
                .title("swagger文档信息")
                .description("swagger_ui_Restful 接口信息")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

3、配置接口信息

package com.supergo.controller;

import com.supergo.ApiBrandFeign;
import com.supergo.http.HttpResult;
import com.supergo.pojo.Brand;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;


/**
 * @Author: xj0927
 * @Description: feign服务调用者
 * @Date Created in 2020-12-23 22:01
 * @Modified By:
 */
@RestController
@RequestMapping("/brand")
//@CrossOrigin  //允许访问该controller的请求进行跨域,在zuul网关中全局配置代替
@Api(value = "品牌控制器", protocols = "http", tags = "品牌控制器")  //controller类说明
public class BrandController {

    @Autowired
    private ApiBrandFeign brandFeign;

    //品牌分页查询
    @ApiOperation(value = "品牌分页查询", notes = "接收分页参数:page,rows") //controller中方法说明
    @ApiImplicitParams({ //对方法接收的参数进行说明
            //第一个参数
            @ApiImplicitParam(paramType = "path", name = "page", value = "第几页", required = true, dataType = "int"),
            @ApiImplicitParam(paramType = "path", name = "rows", value = "一页展示多少行", required = true, dataType = "int")
    })
    @ApiResponses({//响应状态码进行说明
            @ApiResponse(code = 200, message = "条件分页查询品牌成功"),
            @ApiResponse(code = 500, message = "条件分页查询品牌失败,后台服务出现异常"),
            @ApiResponse(code = 401, message = "代表此操作无权访问"),
            @ApiResponse(code = 400, message = "表示请求参数错误"),
    })
    @PostMapping("/query/{page}/{rows}")
    public HttpResult getBrandList(@RequestBody Brand brand, @PathVariable Integer page, @PathVariable Integer rows) {
        HttpResult result = brandFeign.findPage(brand, page, rows);
        return result;
    }

    //根据主键查询品牌
    @ApiOperation(value = "品牌主键查询", notes = "接收查询品牌id参数")
    @ApiImplicitParam(paramType = "path", name = "brandId", value = "品牌id", dataType = "Long", required = true)
    @ApiResponses({//响应状态码进行说明
            @ApiResponse(code = 200, message = "查询品牌成功"),
            @ApiResponse(code = 500, message = "条件分页查询品牌失败,后台服务出现异常"),
            @ApiResponse(code = 401, message = "代表此操作无权访问"),
            @ApiResponse(code = 400, message = "表示请求参数错误"),
    })
    @GetMapping("/{brandId}")
    public HttpResult getBrandById(@PathVariable Long brandId) {
        HttpResult result = brandFeign.getBrandById(brandId);
        return result;
    }
}

4、测试

访问：http://localhost:9001/swagger-ui.html

---

5、Swagger UI 组件

Swagger 默认提供了 API 展示 UI springfox-swagger-ui ，启动工程后可以访问如下路径查看api信息：

http://localhost:9001/swagger-ui.html

国内还有一个优秀的 Swagger-Bootstrap-UI 基于 Swagger 的前端 UI ，采用 jQuery+bootstrap 实现

Swagger 的默认UI 是上下结构的，用起来不太习惯，所以用 Swagger-Bootstrap-UI 替换 Swagger 默认的 UI 实现 左右菜单风格的 Swagger-UI ，让其看起来更清晰明了

使用方法：

（1）添加依赖

<!--Swagger ui组件：和swagger用的同一套json数据,只是其展示的页面结构更加清晰-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.3</version>
</dependency>

---

无论是 原生的 Swagger-ui.html 还是 doc.html 页面展示，它们用的 json 数据都是通过 访问 http://localhost:9999/api/v2/api-docs 拿到的，再根据这个数据进行 接口文档的展示

---

（2）测试使用

访问：

直接访问具体的微服务查看接口文档

再对比一下原生方式：

---