Swagger入门

概述

swagger是一种易用而强大的API开发工具套件(suite)，从设计、编写文档到测试和部署(即整个API生命周期)，它能为个人、团队提供支持。

Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Swagger consists of a mix of open source, free and commercially available tools that allow anyone, from technical engineers to street smart product managers to build amazing APIs that everyone loves.

Swagger is built by SmartBear Software, the leader in software quality tools for teams. SmartBear is behind some of the biggest names in the software space, including Swagger, SoapUI and QAComplete .原文

swagger-ui效果

优势

API DX(developer Experience)很重要，用swagger辅助可帮助你更好的设计、编写、测试和部署API。

API DX重要性体现在：

• 文档(documentation)在DX中的角色。好的API文档的编写需要技巧性(代码示例等)，一个设计良好的API文档会帮助你更好的消费它，把它集成在你的系统里。
• 良好的文档不是一个简单的任务。文档是冗长耗时的(版本更新后，API文档需要随之更新)

原文

API设计最佳实践

良好API设计的特点：

• 易于阅读和使用。
• 混用困难。即理解难以偏差。
• 完整性和精确性。

集合(Collections)，资源(Resources)和他们的URLs

理解集合和资源

资源是REST概念的基础。一个资源是一个对象，资源有数据，与其它资源构成关系。

名词用于描述URLs更佳

The base URL should be neat, elegant, and simple so that developers using your product can easily use them in their web applications.

用HTTP方法来描述资源的功能

Method	Description
GET	Used to retrieve a representation of a resource.
POST	Used to create new new resources and sub-resources
PUT	Used to update existing resources
PATCH	Used to update existing resources
DELETE	Used to delete existing resources

返回（响应）Responses

用反馈帮助开发者成功

给所有GET响应一个例子

请求Request

优雅地处理复杂事情

原文

API注解标签

原文

Quick Annotation Overview

Name	Description
@Api	Marks a class as a Swagger resource.
@ApiImplicitParam	Represents a single parameter in an API Operation.
@ApiImplicitParams	A wrapper to allow a list of multiple ApiImplicitParam objects.
@ApiModel	Provides additional information about Swagger models.
@ApiModelProperty	Adds and manipulates data of a model property.
@ApiOperation	Describes an operation or typically a HTTP method against a specific path.
@ApiParam	Adds additional meta-data for operation parameters.
@ApiResponse	Describes a possible response of an operation.
@ApiResponses	A wrapper to allow a list of multiple ApiResponse objects.
@Authorization	Declares an authorization scheme to be used on a resource or an operation.
@AuthorizationScope	Describes an OAuth2 authorization scope.
@ResponseHeader	Represents a header that can be provided as part of the response.

参考文档

swagger官网
swagger-maven-plugin - kongchen