SpringBoot非常适合开发 Restful API程序, 我们都知道为API文档非常重要, 但要维护好难度也很大, 原因有:

1. API文档如何能被方便地找到? 以文件的形式编写API文档都有这个问题, 使用在线 Wiki 等知识平台部分地能解决这个问题.
2. API文档经常过期. API 接口不断地被改进, 有些项目组使用Word软件编写API文档, 因版本管理难度大, 最后往往是API文档严重过时. 使用 Markdown 格式编写会好一些.

Swagger 是一个非常好的工具, 用的好能解决上面的两个顽疾. Swagger解决方法也很直接:
1. 我们的 Restful API项目自动会暴露一个Swagger UI endpoint 来呈现 API 文档, 访问 http://localhost:8080/swagger-ui.html 即可查看API文档.
2. API 文档是以 Java 注解的形式埋点在代码中, 我们修改Rest API的同时, 顺便就能修改相应的文档注解, Release 新版API.

Swagger 文档主要包括:
1. 一个 Docket 摘要信息
2. 多个 Model 类的说明
3. 多个 Controller 类的说明

SpringBoot 可以使用 SpringFox 直接集成 Swagger 功能, SpringFox同时支持 Swagger1.2 和 Swagger2, 推荐使用 Swagger2, 相关文档 http://springfox.github.io/springfox/docs/current/#springfox-spring-mvc-and-spring-boot

====================================
Swagger常用注解
====================================
我们项目在增加了 @EnableSwagger2 之后, swagger 会很为几乎所有的自定义类生成文档信息(当然 swagger 内置一个 ignore 清单), 背后的技术可能是 reflection 吧, 可以想象通过发射机制生成的文档就是一个代码的缩略版, 用处不大.
要想丰富 swagger 文档, 需要使用它提供的一系列注解, 通过注解表明生成高质量的Api文档,包括接口名、请求方法、参数、返回信息的等等.

@ApiModel: 修饰 Pojo 类.
@ApiModelProperty: 修饰 Pojo 类属性

@Api: 修饰Controller 类, 说明该 controller 的作用
@ApiOperation: 描述 controller类的一个方法, 说明该方法的作用
@ApiImplicitParams: Api方法的参数注解, 通常包含多个 @ApiImplicitParam 注解.
@ApiImplicitParam: 一个具体参数的注解, 该注解需要放在 @ApiImplicitParams 注解内, 该注解的选项有:
        1. paramType 选项: 用来说明参数应该被放置的地方, 有 query/header/pathy/body/form 等取值, query 取值适合于 @RequstParam 参数, header取值适合于@RequestHeader参数, path取值适合于@PathVariable参数, body 取值适合于 @RequestBody 参数.
        2. name 选项: 参数名
        3. dataType 选项: 参数类型
        4. required 选项: 是否必须传
        5. value 选项: 参数值
        6. defaultValue 选项: 参数默认值

@ApiResponses: 为controller方法增加 HTTP响应整体描述, 通常包含多个 @ApiResponse 注解.
@ApiResponse: HTTP响应其中一个描述, 该注解需要放在 @ApiResponses 注解内, 该注解的选项有:
        1. code 选项: 即 httpCode 或 httpStatus, 比如 200 等.
        2. message 选项, code 对应的自定义文字说明.

@ApiIgnore: 让 Swagger 忽略被本注解标注的类/方法/属性. (经我的测试, 2.9.2版不能忽略类).

====================================
pom.xml
====================================
增加 springfox 两个依赖包.

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

====================================
新建一个 SwaggerConfig 配置类
====================================
在项目中需要增加一个 Swagger Config 类, 该类需要加上 @EnableSwagger2 注解, 在该类中需要声明一个 Docket bean, Docket 这个词我理解应该是 DocumentLet 的缩写, 相当于API文档的摘要信息.

@Configuration
@EnableSwagger2
public class SwaggerConfig { /*
* Docket 是 DocumentLet 的缩写, 相当于摘要
*/
@Bean
public Docket createRestApi() {
Docket docklet = new Docket(DocumentationType.SWAGGER_2).apiInfo(metaData())
.select()
// apis() 作用是通过 basePackage 或 withClassAnnotation 来指定swagger扫描的类的范围
.apis(RequestHandlerSelectors.basePackage("com.example.demo"))
// paths() 是通过路径的方式来指定swagger扫描的类的范围
.paths(PathSelectors.any())
.build(); return docklet;
} private ApiInfo metaData() {
return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("学习使用 Swagger2 ")
.contact(new Contact("author name", "http://about.me", "email@email.com"))
.version("1.0")
.build();
}
} /*
*
* //如果集成了 Spring Security , 需要加一个Spring Security配置类允许访问 swagger 相关资源
*
* @Configuration public class SpringSecConfig extends
* WebSecurityConfigurerAdapter {
*
* @Override protected void configure(HttpSecurity httpSecurity) throws
* Exception {
* httpSecurity.authorizeRequests().antMatchers("/","/swagger-resources").
* permitAll(); httpSecurity.csrf().disable();
* httpSecurity.headers().frameOptions().disable(); } }
*/

====================================
Pojo 类
====================================
Pojo 类加上 @ApiModel 注解, 仅仅是能增加点 description 选项. 每个属性可以用 @ApiModelProperty 注解.

@ApiModel(description="Product model object")
class Product {
@ApiModelProperty(notes = "The application-specific product id", dataType = "String")
private String productId;
@ApiModelProperty(notes = "The product description")
private String description;
@ApiModelProperty(notes = "The price of the product", required = true, dataType = "Decimal")
private BigDecimal price; public Product() {
} public static Product getEmptyProduct() {
Product product = new Product();
product.setProductId("===empty===");
return product;
} public Product(String productId, String description, BigDecimal price) {
this.productId = productId;
this.description = description;
this.price = price;
} //省略 getter/setter
}

====================================
Controller 类
====================================
Controller 类是 API 文档的重点, 使用 @Api 注解类, 使用 @ApiOperation/@ApiResponses/@ApiImplicitParams 来注解方法.

@RestController
@RequestMapping("/product")
@Api(tags = "Product Controller", description = "Operations pertaining to products in online store")
class ProductController {
private ProductService productService; @Autowired
void setProductService(ProductService productService) {
this.productService = productService;
} @ApiOperation(value = "view of list of available products", response = Iterable.class)
@ApiResponses(value = { @ApiResponse(code = 200, message = "Sucessfully retrieve list"),
@ApiResponse(code = 401, message = "You are not authorized to view the resource"),
@ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden") })
@RequestMapping(value = "/list", method = RequestMethod.GET, produces = "application/json")
public Iterable<Product> list(Model model) {
return productService.listAllProducts();
} @ApiOperation(value = "Search a product by productId", response = Product.class)
@RequestMapping(value = "/show/{productId}", method = RequestMethod.GET, produces = "application/json")
public Product showProduct(@PathVariable String productId, Model model) {
Optional<Product> optional = productService.getProductById(productId);
return optional.orElse(Product.getEmptyProduct());
}
}

====================================
Service 类
====================================
这里 Service 有一个 ProductService 接口和 ProductServiceImpl 实现类, 它们和 swagger 没有关系.

/*
* Product Service 接口
*/
interface ProductService {
Iterable<Product> listAllProducts(); Optional<Product> getProductById(String productId); Product saveProduct(Product product); void deleteProduct(String productId);
} /*
* Product Service 的实现类
*/
@Service
@Scope("singleton")
class ProductServiceImpl implements ProductService {
private static List<Product> productStore = new ArrayList<Product>(); public ProductServiceImpl() {
productStore.add(new Product("Product1", "About Product1", new BigDecimal("1")));
productStore.add(new Product("Product2", "About Product2", new BigDecimal("2")));
productStore.add(new Product("Product3", "About Product3", new BigDecimal("3")));
} @Override
public Iterable<Product> listAllProducts() {
return productStore;
} @Override
public Product saveProduct(Product product) {
deleteProduct(product.getProductId());
productStore.add(product);
return product;
} @Override
public Optional<Product> getProductById(String productId) {
return productStore.stream()
.filter(p -> productId.equals(p.getProductId()))
.findFirst();
} @Override
public void deleteProduct(String productId) {
productStore.removeIf(p -> p.getProductId()
.equals(productId));
}
}

====================================
测试效果
====================================
访问 http://localhost:8080/swagger-ui.html

====================================
参考
====================================
https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/
https://www.jianshu.com/p/8033ef83a8ed
https://www.jianshu.com/p/be05aa96fd29

SpringBoot系列: 使用 Swagger 生成 API 文档的更多相关文章

  1. .Net Core 3.1 WebApi使用Swagger生成Api文档

    用swagger生成Api文档 1.安装Swashbuckle.AspNetCore 右键单击"解决方案资源管理器" > "管理 NuGet 包"中的项目 ...

  2. springboot+mybatis-puls利用swagger构建api文档

    项目开发常采用前后端分离的方式.前后端通过API进行交互,在Swagger UI中,前后端人员能够直观预览并且测试API,方便前后端人员同步开发. 在SpringBoot中集成swagger,步骤如下 ...

  3. 12 Django Rest Swagger生成api文档

    01-简介 Swagger:是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新.当接口有变动时,对应的接 ...

  4. SpringBoot结合Swagger2自动生成api文档

    首先在pom.xml中添加如下依赖,其它web,lombok等依赖自行添加 <dependency> <groupId>io.springfox</groupId> ...

  5. SpringBoot+rest接口+swagger2生成API文档+validator+mybatis+aop+国际化

    代码地址:JillWen_SpringBootDemo mybatis 1. 添加依赖: <dependency> <groupId>org.mybatis.spring.bo ...

  6. ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介

    参考地址,官网:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view ...

  7. Laravel(PHP)使用Swagger生成API文档不完全指南 - 基本概念和环境搭建 - 简书

    在PHPer中,很多人听说过Swagger,部分人知道Swagger是用来做API文档的,然而只有少数人真正知道怎么正确使用Swagger,因为PHP界和Swagger相关的资料实在是太少了.所以鄙人 ...

  8. 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (上篇)

    前言 为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...

  9. 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

    前言 回顾上一篇文章<使用Swagger做Api文档 >,文中介绍了在.net core 3.1中,利用Swagger轻量级框架,如何引入程序包,配置服务,注册中间件,一步一步的实现,最终 ...

随机推荐

  1. formatter的使用

    1.目的 如图所示,实现行编辑栏中的编辑删除,以及在时间建议中显示上中下旬 可参考easyui官方文档中所写的关于datagrid列属性:http://www.jeasyui.net/plugins/ ...

  2. Spring boot admin 节点状态一直为DOWN的排查

    项目中需要监控各个微服务节点的健康状态,找到了spring boot admin这个全家桶监控工具,它其实是Vue.js美化过的Spring Boot Actuator,官方的解释是: codecen ...

  3. 周末班:Python基础之模块

    什么是模块 什么是模块? 常见的场景:一个模块就是一个包含了python定义和声明的文件,文件名就是模块名字加上.py的后缀. 但其实import加载的模块分为四个通用类别: 1 使用python编写 ...

  4. python之常用模块

    python 常用模块 之 (subprocess模块.logging模块.re模块) python 常用模块 之 (序列化模块.XML模块.configparse模块.hashlib模块) pyth ...

  5. 苹果绿RGB值

    ESL的值为:85,123,205 RGB的值为:199,237,204 ESL和RGB只需填一个即可,另一个会自动调整~

  6. 使用sz/rz基于串口传输文件

    关键词:lrzsz.minicom.ZMODEM.MD5sum等. 在环境受限的嵌入式系统上,往往只有串口可以使用. 此时如果需要传输文件,需要借助rz/sz工具,可以使用的传输协议有ZMODEM.Y ...

  7. 微服务领域是不是要变天了?Spring Cloud Alibaba正式入驻Spring Cloud官方孵化器!

    引言 微服务这个词的热度自它出现以后,就一直是高烧不退,而微服务之所以这么火,其实和近几年互联网的创业氛围是分不开的. 与传统行业不同,互联网企业有一个特点,那就是市场扩张速度非常之快,可能也就是几天 ...

  8. 获取任意链接文章正文 API 功能简介

    此文章对开放数据接口 API 之「获取任意链接文章正文」进行了功能介绍.使用场景介绍以及调用方法的说明,供用户在使用数据接口时参考之用. 1. 产品功能 接口开放了根据提供的文章链接 Url 参数,智 ...

  9. python 项目自动生成requirements.txt文件

    主要使用目的: 任何应用程序通常需要设置安装所需并依赖一组类库来满足工作要求.通过requirements.txt可以一次性安装程序所需要和依赖的包. 为工程生成requirements.txt的两种 ...

  10. tomcat 启动窗口乱码

    在tomcat主目录下的conf文件夹里,找到logging.properties文件: 用记事本打开,找到以下内容 java.util.logging.ConsoleHandler.encoding ...