SpringBoot之Swagger2文档生成

时间 2019-11-26

标签 springboot swagger2 swagger 文档生成栏目 Spring 繁體版

原文原文链接

SpringBoot之Swagger2文档生成

一、Swagger2介绍

编写和维护接口文档是每一个程序员的职责，前面咱们已经写好的接口如今须要提供一份文档，这样才能方便调用者使用。考虑到编写接口文档是一个很是枯燥的工做，咱们采用Swagger2这套自动化文档工具来生成文档，它能够轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。 html

二、SpringBoot开启Swagger2支持

第一步：在pom.xml中加入Swagger2的依赖程序员

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

第二步：建立Swagger2配置类spring

package com.offcn.config;api

import org.springframework.context.annotation.Bean;app

import org.springframework.context.annotation.Configuration;工具

import springfox.documentation.builders.ApiInfoBuilder;ui

import springfox.documentation.builders.PathSelectors;spa

import springfox.documentation.builders.RequestHandlerSelectors;3d

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage("com.offcn.controller"))

.paths(PathSelectors.any())

.build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("Spring Boot中使用Swagger2构建RESTful APIs")

.description("优就业")

.termsOfServiceUrl("http://www.ujiuye.com/")

.contact("Sunny")

.version("1.0")

.build();

}

三、修改Controller增长文档注释

经过@ApiOperation注解来给API增长说明经过@ApiImplicitParams@ApiImplicitParam注解来给参数增长说明

/**

* 更新指定id用户信息

* @param id

* @param user

* @return

@PutMapping("/{id}")

@ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息")

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),

@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")

})

public String updateUser(@PathVariable("id") Long id,User user) {

user.setId(id);

userRepository.saveAndFlush(user);

return "success";

}

/***

* 删除指定id用户

* @param id

* @return

@DeleteMapping("/{id}")

@ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")

@ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")

public String deleteUser(@PathVariable("id") Long id) {

userRepository.deleteById(id);

return "success";

}

四、查看Swagger2文档

重启应用访问地址：http://localhost:8080/swagger-ui.html

点开每一个接口，能够查看接口详情