手记

【九月打卡】第七天 Swagger2接口文档工具的使用

课程名称:Spring Cloud 进阶 Alibaba 微服务体系自媒体实战
课程章节: 第2章 架构后端项目
主讲老师: 风间影月

课程内容

在正常的工作当中,后端需要编写对应的接口文档。而传统的通过Word的方式存在一些格式难以控制、更新慢等一些问题。所以引入在线的Swagger接口文档。

项目嵌入Swagger的具体步骤为:

  1. 引入依赖

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>
  1. 创建配置类com.imooc.api.config.Swagger2

package com.imooc.api.config;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig2 {

    // 配置swagger2核心配置 docket
    @Bean
    public Docket createRestApi() {

        Predicate<RequestHandler> adminPredicate = RequestHandlerSelectors.basePackage("com.imooc.admin.controller");
        Predicate<RequestHandler> articlePredicate = RequestHandlerSelectors.basePackage("com.imooc.article.controller");
        Predicate<RequestHandler> userPredicate = RequestHandlerSelectors.basePackage("com.imooc.user.controller");
        Predicate<RequestHandler> filesPredicate = RequestHandlerSelectors.basePackage("com.imooc.files.controller");

        return new Docket(DocumentationType.SWAGGER_2)  // 指定api类型为swagger2
                    .apiInfo(apiInfo())                 // 用于定义api文档汇总信息
                    .select()
                    .apis(Predicates.or(adminPredicate, articlePredicate, userPredicate, filesPredicate))
                    .paths(PathSelectors.any())         // 所有controller
                    .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("慕课新闻·自媒体接口api")                       // 文档页标题
                .contact(new Contact("imooc",
                        "https://www.imooc.com",
                        "abc@imooc.com"))                   // 联系人信息
                .description("专为慕课新闻·自媒体平台提供的api文档")      // 详细信息
                .version("1.0.1")                               // 文档版本号
                .termsOfServiceUrl("https://www.imooc.com")     // 网站地址
                .build();
    }

}
  1. 为controller添加api注解:

@Api(value = "controller标题", tags = {"xx功能controller"})
  1. 为接口添加注解:

@ApiOperation(value = "hello方法", notes = "hello方法", httpMethod = "GET")

课程收获

注解详情

@Api

用在类上,该注解将一个Controller(Class)标注为一个swagger资源(API)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。该注解包含以下几个重要属性

  • tags API分组标签。具有相同标签的API将会被归并在一组内展示。

  • value 如果tags没有定义,value将作为Api的tags使用

  • description API的详细描述,在1.5.X版本之后不再使用,但实际发现在2.0.0版本中仍然可以使用

@ApiOperation

在指定的(路由)路径上,对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有:

  • value 对操作的简单说明,长度为120个字母,60个汉字。

  • notes 对操作的详细说明。

  • httpMethod HTTP请求的动作名,可选值有:"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。

  • code 默认为200,有效值必须符合标准的HTTP Status Code Definitions

@ApiImplicitParams

用在方法上,注解ApiImplicitParam的容器类,以数组方式存储。

@ApiImplicitParam

对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定,但这个@ApiImplicitParam注解可以以统一的方式定义参数列表,也是在Servelet及非JAX-RS环境下,唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性:

  • name 参数名称

  • value 参数的简短描述

  • required 是否为必传参数

  • dataType 参数类型,可以为类名,也可以为基本类型(String,int、boolean等)

  • paramType 参数的传入(请求)类型,可选的值有path, query, body, header or form。

@ApiParam

增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有

  • required 是否为必传参数,默认为false

  • value 参数简短说明


课程截屏


0人推荐
随时随地看视频
慕课网APP