一、是一款让你更好的书写API文档的规范且完整框架。
二、提供描述、生产、消费和可视化RESTful Web Service。
三、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。html
一、在pom.xml文件中添加第三方swagger依赖()git
<dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.7.0.RELEASE</version> </dependency>
二、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解,就能够直接使用啦。
三、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目,里面有详细的讲解。github
<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>
须要特别注意的是swagger scan base package,这是扫描注解的配置,即你的API接口位置。web
import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; 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 Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台 APIs") .description("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台") .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin") .contact("程序猿") .version("1.0") .build(); } }
//本controller的功能描述 @Api(value = "pet", description = "the pet API") public interface PetApi { //option的value的内容是这个method的描述,notes是详细描述,response是最终返回的json model。其余能够忽略 @ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = { @Authorization(value = "petstore_auth", scopes = { @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"), @AuthorizationScope(scope = "read:pets", description = "read your pets") }) }, tags={ "pet", }) //这里是显示你可能返回的http状态,以及缘由。好比404 not found, 303 see other @ApiResponses(value = { @ApiResponse(code = 405, message = "Invalid input", response = Void.class) }) @RequestMapping(value = "/pet", produces = { "application/xml", "application/json" }, consumes = { "application/json", "application/xml" }, method = RequestMethod.POST) ResponseEntity<Void> addPet( //这里是针对每一个参数的描述 @ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body);
在配置文件中,application.yml中声明:spring
springfox.documentation.swagger.v2.path: /api-docs
这个path就是json的访问request mapping.能够自定义,防止与自身代码冲突。json
API doc的显示路由是:http://localhost:8080/swagger-ui.htmlapi
若是项目是一个webservice,一般设定home / 指向这里:安全
@Controller public class HomeController { @RequestMapping(value = "/swagger") public String index() { System.out.println("swagger-ui.html"); return "redirect:swagger-ui.html"; } }
Api 用在类上,说明该类的做用。能够标记一个Controller类作为swagger 文档资源,使用方式:
@Api(value = "/user", description = "Operations about user")
app
ApiOperation:用在方法上,说明方法的做用,每个url资源的定义,使用方式:框架
@ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"})
ApiParam请求属性,使用方式:
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)
ApiResponse:响应配置,使用方式:
@ApiResponse(code = 400, message = "Invalid user supplied")
ApiResponses:响应集配置,使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
响应头设置,使用方法
@ResponseHeader(name="head1",description="response head conf")