前言
使用RESTful服务通常是涉及到多个终端的团队，比如Android、iOS、WEB等。为了让大家沟通顺畅，通常我们需要编写一份详细的RESTful业务接口文档
使用Swagger2有助于我们编写一份详细的RESTful业务接口文档，过去经常会使用Word或者Excel，但是接口非常多，细节又复杂，如果由程序员高质量的输出一个文档，经常耗时长而且效果也不好。Swagger2能将代码和注释说明很好结合在一块。既减轻了研发人员的负担，又能输出高质量的文档。
下面说下如何去使用
pom.xml中添加Swagger2依赖
<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>
创建Swagger2配置类
@Configuration注解，让Spring来加载该类配置。 @EnableSwagger2注解来启用Swagger2。 apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。 RequestHandlerSelectors.basePackage()中填的是你controller的目录 apiInfo()方法中termsOfServiceUrl和contact可以用Contact的对象代替
注意：
Swagger2已经不支持String类型的contact
Contact对象中name表示作者，url通常作为项目的链接，代替之前的termsOfServiceUrl方法，email的话不用我多说了吧，不想写的话可以为空字符串
createRestApi函数创建Docket的Bean之后，apiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
**select()**函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
@Configuration @EnableSwagger2 public class SwaggerConfig{ /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现， * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.pjb.controller")) .paths(PathSelectors.any()) .build(); } /** * 创建该API的基本信息（这些基本信息会展现在文档页面中） * 访问地址：http://项目实际地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { Contact contact=new Contact("作者名", "http://zjc.com","email地址"); return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2") .description("Hello Swagger2") //.termsOfServiceUrl("http://www.jianshu.com/u/f192766abeab") //.contact("作者名") .contact(contact) .version("1.0") .build(); } }
然后通过创建实体类和controller来简单测试下
@RestController @RequestMapping("user") public class UserController { @Autowired UserService userService; @GetMapping(value="/findAll") @ApiOperation(value = "查询所有用户",httpMethod ="GET", response = User.class,notes = "HelloWorld") public List<User> findAll(){ return userService.findAll(); } }
注意:
记得在UserController中需要id输入的方法的注解少了个参数配置： paramType=“path”，不然所有的参数类型都会是body，获取不到请求参数。例如
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “Long”，paramType = “path”)；
访问：http://localhost:8080/swagger-ui.html
就能看到前文所展示的RESTful API的页面。
我们还可以进行Try it out 进行测试，赶紧试试吧，满意请点赞收藏，么么哒
