Swagger怎么用? 其实就是这么简单

1、swagger 是什么？

​ Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

---

2、如何使用？

1、引入依赖

<!-- Swagger 第一种方式-->
	<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.1.RELEASE</version>
	</dependency>
	
	
<!--swagger2接口文件 第二种方式-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

2、注解使用

@EnableSwagger2Doc（第一种方式引入依赖注解方式）

@EnableSwagger2（第二种）

/**
 * 第一种方式
 *
 * @author pengwei
 * @date 2020/12/25
 */

@SpringBootApplication
//@EnableSwagger2Doc
//@EnableSwagger2
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(AuthApplication.class, args);
    }
}

3、配置类（推荐）

/**
 *	 固定配置
 * @author pengwei
 * @date 2020/12/25
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-课程中心API文档")
                .description("本文档描述了课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("java", "。。。。。", "1123@qq.com"))
                .build();
    }
}

如果是单独给swagger建立了一个Maven ，引入到其他服务中，可以这样做

在启动类加上@ComponentScan(“xxx.xx”) 自动扫描组件

​ @ComponentScan(“xxx.xx”) 指定要扫描的包

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-BIU0EieB-1608914865720)(imgs/image-20201226001317600.png)]

---

5、在线测试接口

http://localhost:8000/swagger-ui.html#/

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-n3tfsITj-1608914865727)(imgs/image-20201226004146002.png)]

---

6、注解配置 ：

官网Wiki地址：https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview

• @Api

//描述controller类
@Api(tags = {"external_info","user_info"})

• @ApiOperation 描述一个方法或者一个API接口

// value = ""  描述方法
// notes = ""  描述方法详细信息
 @ApiOperation(value = "Finds Pets by status",
    notes = "Multiple status values can be provided with comma seperated strings",
    response = Pet.class,
    responseContainer = "List")
 public Response findPetsByStatus(...) { ... }

• ApiImplicitParam

 @ApiImplicitParam(name = "id", value = "User ID", required = true, dataType = "long", paramType = "query")
  )
 public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {...}

• @ApiImplicitParams 描述方法或接口参数

    /**
     *    name = ""方法或接口的形参, 注意要与方法的参数名称相同
     *    value = "" 对参数的描述
     *    paramType = "" 参数传递方式，此属性的可选值 ["header", "query", "path", "body", "form"]
     *          1. header，使用@RequestHeader获取的参数
     *          2. query，使用@RequestParam获取的参数，常用于GET请求
     *          3. path，使用@PathVariable获取的参数
     *          4. body，使用@RequestBody获取的参数，常用于POST请求，对象参数
     *   dataType = "" 参数类型，例如 string, int, ArrayList, POJO类
     */
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "User's name", required = true, dataType = "string", paramType = "query"),
    @ApiImplicitParam(name = "email", value = "User's email", required = false, dataType = "string", paramType = "query"),
    @ApiImplicitParam(name = "id", value = "User ID", required = true, dataType = "long", paramType = "query")
  })
 public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {...}

注：还有一部分大家可以去wiki官网上看哦，加深印象。

---

如果有讲的不对的地方，欢迎大家留言讨论。