程序员的痛(文档): 在线文档神器-swagger3.0 接入

@[TOC](程序员的痛(文档): 在线文档神器-swagger3.0 接入)

前言

​ 作为一名攻城狮，工作过程文档的单独维护，其实一直是一个很让人 头疼的问题；于是就出现很多的插件工具帮助我们来自动的维护文档，提高生产力；其中 swagger就是一个 被 广泛使用的工具；他的升级版本 swagger3.0 也来了；这解决了多少人的 痛啊；但是，他也不是没有缺陷，如果编码 不够规范，入参/结果封装类维护不好，swagger的文档会让人看起来很头疼。废话不说直接开干。

接入过程

maven依赖

<!--       swagger3      -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

config配置

@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("联系beauty,共同进步,一起成长。")
                .contact(new Contact("beauty。", "https://blog.csdn.net/qq_41692766", "yufw1066@qq.com"))
                .version("1.0")
                .build();
    }
}

开启swagger两种方式

1. 在启动类添加@EnableOpenApi

@EnableOpenApi
@SpringBootApplication
public class CommonOpenApiApplication {

    public static void main(String[] args) {
        SpringApplication.run(CommonOpenApiApplication.class, args);
    }

}

2. yml配置文件

# swagger3.0
springfox:
  documentation:
    swagger-ui:
      enabled: true # true放开api文档，false关闭api文档

controller接口编写及配置

@Api(tags = "demo-api")
@RestController
@RequestMapping("/api")
public class DemoApi {

    /**
     * demo
     *
     * @return hello
     */
    @ApiOperation("demo-test")
    @GetMapping("/welcome")
    public String demo(){
        return "hello, welcome to beauty";
    }


}

常用注解(后续会补充完善)：

- **@Api()**用于类；
表示标识这个类是swagger的资源
- **@ApiOperation()**用于方法；
表示一个http请求的操作
- **@ApiParam()**用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- **@ApiModel()**用于类
表示对类进行说明，用于参数用实体类接收
- **@ApiModelProperty()**用于方法，字段
表示对model属性的说明或者数据操作更改
- **@ApiIgnore()**用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

源码地址: https://gitee.com/yufw1214/beauty/tree/master/beauty-openapi

如有问题,欢迎大家提出交流