# obsidian-swagger

**Repository Path**: cloudladder/obsidian-swagger

## Basic Information

- **Project Name**: obsidian-swagger
- **Description**: 基于swagger2和swagger-ui的api文档生成套件，全新的界面风格，更舒适的交互体验，以及对swagger原有功能的增强和扩展
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: http://obsidian.cloudladder.com.cn
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 1
- **Created**: 2021-09-17
- **Last Updated**: 2023-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: API, Swagger, 接口管理

## README

# obsidian-swagger

![obsidian-swagger界面](https://images.gitee.com/uploads/images/2021/0928/171719_4d4cc5f0_1728861.png "obsidian-swagger.png")


#### 试用地址
http://obsidian.cloudladder.com.cn


#### 开始

1.  在你的maven工程的pom.xml中添加依赖（前提是一个基于spring-boot的web工程）

```
<dependency>
    <groupId>io.gitee.cloudladder</groupId>
    <artifactId>obsidian-swagger-ui</artifactId>
    <version>1.0.3</version>
</dependency>

<dependency>
    <groupId>io.gitee.cloudladder</groupId>
    <artifactId>obsidian-swagger2</artifactId>
    <version>1.0.3</version>
</dependency>
```
2.  配置swagger（和swagger的配置一样）

```
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.buildApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("io.gitee.cloudladder.obsidian.swagger2.example"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInfo() {
        return new ApiInfoBuilder().title("Api Document Example")
                .description("Api document for example, ")
                .license("Apache Licence 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.txt")
                .termsOfServiceUrl("xxxxx")
                .contact(new Contact("cloudladder", "https://gitee.com/cloudladder/obsidian-swagger", "xxx@126.com"))
                .version("1.0")
                .build();
    }

}
```
3.  启动spring-boot应用，访问你的web服务的根路径（例如：http://localhost:8080/ ）


#### 概述
obsidian-swagger是基于springfox-swagger2及springfox-swagger-ui的二次封装，同样用于基于spring-mvc的服务端api自动生成，具备以下特点：
- 全新页面风格，更友好的交互；
- 支持api排序；
- 支持api搜索（根据请求路径、名称、描述的模糊搜索）；
- 支持自定义Response对象的ErrorCode扩展；
- 支持自定义Response示例；
- 支持了@RequestPart标注的String、Integer、Double、Boolean等基本类型参数的api在线调试（springfox-swagger-ui不支持这类文档调试)；
- 在调试页面中，自动识别String、Integer、Double、Boolean、Date等类型参数，并选择交互方式更好的输入控件；


#### 扩展注解
- @ApiOperationSort：控制api排序，传入一个int参数；
- @ApiResponseExample：自定义api response example，参数类型为Class<?>，可自定义一个Generator，需实现ResponseExampleGenerator<T>接口，接口中返回api response example对象；
- @ApiErrorCodes：自定义返回类型中的自定义错误码，参数为一个数组，需传入@ApiErrorCode注解集合；
- @ApiErrorCode：需要code和message参数；

扩展注解代码示例：
```
    @PostMapping("/user")
    @ApiOperationSort(2)
    @ApiOperation(value = "create a user object", notes = "notes for create user")
    @ApiResponseExample(CreateUserResponseExampleGenerator.class)
    @ApiErrorCodes({
            @ApiErrorCode(code = 1000002, message = "age is too max!"),
            @ApiErrorCode(code = 1000003, message = "sex is matched a wrong value!")
    })
    public Response<String> createUser(@RequestBody User user) {
        log.info("create user, user = {}", user);
        return new CreateUserResponseExampleGenerator().generate();
    }
```

#### 其它
- 如不需要使用扩展注解，只引用obsidian-swagger-ui即可
- obsidian-swagger-ui和springfox-swagger-ui可共存，如使用obsidian-swagger-ui，可将springfox-swagger-ui依赖删除，避免不必要的资源浪费

#### 需求与建议
如有需求或建议，请提交至：https://gitee.com/cloudladder/obsidian-swagger/issues ，将会第一时间做出响应

#### 感谢
感谢芦大米同学贡献Logo设计

#### 版权
本项目遵循[Apache Licence 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)协议