当前位置 : 首页 » 文章分类 :  开发  »  Swagger

Swagger

Rest Api 文档自动生成工具 Swagger


SpringBoot中使用Swagger生成API文档

maven 引入 swagger 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>

<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.4.5-RELEASE</version>
</dependency>

springfox-swagger2 负责扫描所有 swagger 注解生成 json 格式的 api 文档
springfox-swagger-ui 根据 json 文档 生成 html 页面

@EnableSwagger2Doc

Application 类上加注解 @EnableSwagger2Doc 启用 swagger,这个注解是 swagger-spring-boot-starter 包提供的,内部包含自动配置类。

@Api controller类名 描述controller
@ApiOperation controller方法 描述接口方法
@ApiParam path 或 param参数 描述接口参数
@ApiImplicitParams, @ApiImplicitParam 参数增加说明。

@ApiModel 实体类名 描述实体
@ApiModelProperty 实体属性 描述属性

json数据地址和ui界面地址

启动项目后打开
http://localhost:8080/v2/api-docs
能看到 json 格式的接口描述

http://localhost:8080/swagger-ui.html
查看 ui 界面

Spring Boot中使用Swagger2构建强大的RESTful API文档 - 程序猿DD
http://blog.didispace.com/springbootswagger2/

java.lang.NumberFormatException: For input string: “”

对于标注了 @ApiModelProperty 的 Integer long 等字段, swagger 在给其生成默认值的时候,会读取 example 值,这个 example 默认是 空字符串,转为 整型 或 Long 型 时 Long.valueOf() Integer.valueOf() 方法会报错。加上数字默认值就行了。

@Data
@ApiModel(description = "接口返回")
public class ResponseDTO {
    @JsonProperty("rtn")
    @ApiModelProperty(value = "返回码", example = "200")
    private Integer rtn;

    @JsonProperty("message")
    @ApiModelProperty(value = "描述信息")
    private String message;
}

Swagger2Markup

Swagger2Markup 是 Github 上的一个开源项目。该项目主要用来将 Swagger 自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。

Swagger2Markup / swagger2markup
https://github.com/Swagger2Markup/swagger2markup


Api2Doc

Swagger 比较臃肿,不太友好,偶然发现一个 Api2Doc 项目,和我们平常工作中用的 ShowDoc 文档非常相似,简洁又清晰。

terran4j/commons
https://github.com/terran4j/commons/tree/master/commons-api2doc

还在用 Swagger2 生成 Restful API 文档?来试试 Api2Doc 吧
https://my.oschina.net/u/3017144/blog/1679922

用Api2Doc代替Swagger2生成 Restful API 文档
https://www.jianshu.com/p/281df3ecd3b0


上一篇 Spring-Boot-Actuator

下一篇 REST

阅读
评论
508
阅读预计2分钟
创建日期 2019-04-29
修改日期 2020-07-21
类别
标签

页面信息

location:
protocol:
host:
hostname:
origin:
pathname:
href:
document:
referrer:
navigator:
platform:
userAgent:

评论