# openapi-swagger

**Repository Path**: fhjx/openapi-swagger

## Basic Information

- **Project Name**: openapi-swagger
- **Description**: openapi-swagger学习：

1.  使用openapi-generator-maven-plugin，生成代码
2.  使用swagger-codegen-cli.jar生成代码
3.  使用swagger-ui和yaml配置生成接口文档
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-24
- **Last Updated**: 2024-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 接口文档

## Swagger

### 1. 概念

是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
Swagger 是一个简单但功能强大的 API 表达工具。使用 Swagger 生成 API，我们可以得到交互式文档，自动生成代码的 SDK (软件开发工具包)以及 API 的发现特性等。

### 2. 特点

1. Api 框架
2. restful Api 文档在线自动生成工具
3. 可以直接运行，在线测试 api 接口
4. 支持多种语言：java、php...

### 3. 常用注解

1. APiModel：实体类
2. ApiModelProperty：实体属性
3. Api:接口类
4. ApiOperation：接口方法的说明
5. @ApiImplicitParams、@ApiImplicitParam：方法参数的说明
6. @ApiResponses @ApiResponse：方法返回值的说明
7. dataType 属性：参数类型，可传基本类型、类、泛型类等
8. ParamType 属性： 表示参数放在哪个位置

   - header-->请求参数的获取：@RequestHeader(代码中接收注解)
   - query-->请求参数的获取：@RequestParam(代码中接收注解)
   - path（用于 restful 接口）-->请求参数的获取：@PathVariable(代码中接收注解)
   - body-->请求参数的获取：@RequestBody(代码中接收注解)
   - form（不常用）

### 4. swagger-ui demo

**SpringBoot 项目使用 Swagger-UI 步骤：​**

- 导入依赖；
- 开启 Swagger 注解：@EnableSwagger2；
- 编写配置类。

```xml
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger ui，访问页面为swagger-ui.html-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- bootStrap-ui,只是在改变页面效果，默认的是swagger-ui.html;使用bootstrap后，为doc.html -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.2</version>
</dependency>
```

```java
@Configuration//配置类
@EnableSwagger2 //swagger注解
public class SwaggerConfig {
    // 创建 swagger 的 Docket 的 bean 实例，使用注解@Bean；如需配置多个分组，则创建多个docket实例
    @Bean
    public Docket docket(Environment environment) {
        // 设置显示的swagger环境信息
        Profiles profiles = Profiles.of("dev", "test");
        // 判断是否处在自己设定的环境当中
        boolean flag  = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("党博")  // 配置api文档的分组
                .enable(flag)  // 配置是否开启swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dangbo.controller")) //配置扫描路径
                .paths(PathSelectors.none()) // 配置过滤哪些
                .build();
    }
    // api基本信息
    private ApiInfo apiInfo() {
        return new ApiInfo("my first swagger",
                "党博的第一个swagger",
                "v1.0",
                "http://mail.qq.com",
                new Contact("dangbo", "http://mail.qq.com", "1456131152@qq.com"),  //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}
```
## Knife4j
   
1. i18n 国际化
2. 接口添加作者
3. 自定义文档
4. 访问权限控制
5. 导出离线文档

## OpenAPI