api文档生成——Swagger(不支持离线文档)

1)简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是：

1. 使得前后端分离开发更加方便，有利于团队协作

2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担

3. 功能测试

   Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

2)SpringBoot集成Swagger

引入依赖,在 study-leadnews模块中引入该依赖

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

API文档技术会扫描指定的【Controller】，而所有微服务都依赖了study-leadnews-core-controller，我们可以直接在该工程中实现对Swagger的配置， 在study-leadnews-core-controller工程的config包中添加一个配置类，代码如下：

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

   /**
    * 创建API文档信息
    * @return
    */
   @Bean
   public Docket buildDocket() {
      HashSet<String> strings = new HashSet<>();
      strings.add("application/json");

      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(buildApiInfo())
              //设置返回值数据类型为json
              .produces(strings)
              .select()
              // 要扫描的API(Controller)基础包
              .apis(RequestHandlerSelectors.basePackage("com.itheima"))
              .paths(PathSelectors.any())
              .build();
   }

   /**
    * 定义Swagger文档信息
    * @return
    */
   private ApiInfo buildApiInfo() {
      Contact contact = new Contact("黑马程序员","","");
      return new ApiInfoBuilder()
              .title("黑马头条-平台管理API文档")
              .description("平台管理服务api")
              .contact(contact)
              .version("1.0.0").build();
   }
}

3)Swagger常用注解

@Api：修饰整个类，描述Controller的作用  

@ApiOperation：修饰类的一个方法 标识 操作信息 接口的定义

@ApiParam：单个参数的描述信息  

@ApiModel：描述使用到的对象信息

@ApiModelProperty：描述使用到的对象的属性信息

@ApiResponse：HTTP1响应其中1个描述  

@ApiResponses：HTTP响应整体描述  

@ApiIgnore：使用该注解忽略这个API  

@ApiError：发生错误返回的信息  

@ApiImplicitParam：一个请求参数  

@ApiImplicitParams：多个请求参数的描述信息

 

 我们在controller中添加Swagger注解，代码如下所示：

@Api(value = "频道管理", tags = "AdChannelController", description = "频道管理")
public class AdChannelController {}

在study-leadnews-admin-api中和study-common中【pojo】中代码中添加【注解ApiModel】和【ApiModelProperties】如下：

AdChannel:

@Data
@EqualsAndHashCode(callSuper = false)
@TableName("ad_channel")
@ApiModel(description = "频道",value="AdChannel")
public class AdChannel implements Serializable {

    @ApiModelProperty(notes = "ID")
    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;

    @ApiModelProperty(notes = "频道名字")
    @TableField("name")
    private String name;

    @ApiModelProperty(notes = "频道描述")
    @TableField("description")
    private String description;

    @ApiModelProperty(notes = "是否是默认频道")
    @TableField("is_default")
    private Integer isDefault;

    @ApiModelProperty(notes = "状态")
    @TableField("status")
    private Integer status;

    @ApiModelProperty(notes = "排序")
    @TableField("ord")
    private Integer ord;

    @ApiModelProperty(notes = "创建时间")
    @TableField("created_time")
    private LocalDateTime createdTime;
}

分页查询请求条件封装对象：

@NoArgsConstructor
@AllArgsConstructor
@Data
@ApiModel(description = "分页请求对象",value="PageRequestDto")
public class PageRequestDto<T> implements Serializable {
    //当前页码
    @ApiModelProperty(notes = "当前页码")
    private Long page = 1L;
    //每页显示的行
    @ApiModelProperty(notes = "每页显示的行")
    private Long size = 10L;
    //请求体实体对象
    @ApiModelProperty(notes = "请求体条件对象")
    private T body;
}

分页查询响应信息封装对象PageInfo，代码如下：

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "通用分页查询返回响应结果对象", value = "PageInfo")
public class PageInfo<T> implements Serializable {
    //当前页码
    @ApiModelProperty(notes = "当前页")
    private Long page;
    //每页显示行
    @ApiModelProperty(notes = "每页条数")
    private Long size;
    //总记录数
    @ApiModelProperty(notes = "总记录数")
    private Long total;
    //总页数
    @ApiModelProperty(notes = "总页数")
    private Long totalPages;
    //当前页记录
    @ApiModelProperty(notes = "结果集")
    private List<T> list;
}

官方的注解说明如下：掌握常见的即可

https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X

Swagger文档虽然很好用，但是不支持离线文档，如果想支持离线文档，我们需要使用knife4j，因为它功能更强大，支持离线文档。

---