http://springfox.github.io/springfox/docs/current/#customizing-the-swagger-endpoints

一、什么是Swagger？

Swagger:? 一個(gè)描述Restful service規(guī)范

?????????????? 可以在界面上測試RestfulService

swagger-ui: 用來顯示API文檔

swagger-editor： 就是一個(gè)在線編輯文檔說明文件（swagger.json或swagger.yaml文件）的工具，以方便生態(tài)中的其他小工具（swagger-ui）等使用

swagger-validator: 這個(gè)小工具是用來校驗(yàn)生成的文檔說明文件是否符合語法規(guī)定的。用法非常簡單，只需url地址欄，根路徑下加上一個(gè)參數(shù)url，參數(shù)內(nèi)容是放swagger說明文件的地址。即可校驗(yàn)。

swagger-codegen: 代碼生成器，腳手架。可以根據(jù)swagger.json或者swagger.yml文件生成指定的計(jì)算機(jī)語言指定框架的代碼。

?

二、Swagger 和 Springfox-Swagger

What is the relationship between swagger-ui and springfox-swagger-ui?
??? Swagger Spec is a specification.
??? Swagger Api - an implementation of that specification that supports jax-rs, restlet, jersey etc.
??? Springfox libraries in general - another implementation of the specification focused on the spring based ecosystem.
??? Swagger.js and Swagger-ui - are client libraries in javascript that can consume swagger specification.
??? springfox-swagger-ui - the one that you’re referring to, is just packaging swagger-ui in a convenient way so that spring services can serve it up.

翻譯下來就是：
swagger-ui 和 springfox-swagger-ui 的關(guān)系是？
??? Swagger Spec 是一個(gè)規(guī)范。
??? Swagger Api 是 Swagger Spec 規(guī)范 的一個(gè)實(shí)現(xiàn)，它支持 jax-rs, restlet, jersey 等等。
??? Springfox libraries 是 Swagger Spec 規(guī)范 的另一個(gè)實(shí)現(xiàn)，專注于 spring 生態(tài)系統(tǒng)。
??? Swagger.js and Swagger-ui 是 javascript 的客戶端庫，能消費(fèi)該規(guī)范。
??? springfox-swagger-ui 僅僅是以一種方便的方式封裝了 swagger-ui ，就是可以顯示文檔內(nèi)容

?

三、Springboot 與Swagger集成

1. 增加下面maven 引用

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

?

2. 增加一個(gè)Swaagger configuration

?

package com.example.config;import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;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;@Configuration public class Swagger2UiConfiguration extends WebMvcConfigurerAdapter {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("org.springframework.boot")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("springboot利用swagger構(gòu)建api文檔").description("簡單優(yōu)雅的restful風(fēng)格，http://XX").termsOfServiceUrl("http://XXx").version("1.0").build();}}

?3.Spring Boots Application 類增加 @EnableSwagger2

?

?

import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.swagger2.annotations.EnableSwagger2;@SpringBootApplication @EnableSwagger2 public class UserApplication1 {public static void main(String[] args) {SpringApplication.run(UserApplication1.class, args);} }

?4. 在Controller 中增加相對應(yīng)的API注釋

package com.example.demo;import java.util.concurrent.atomic.AtomicLong;import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation;@RestController public class GreetingController {private static final String template = "Hello, %s!";private final AtomicLong counter = new AtomicLong();@ApiOperation(value="獲取Greeting info", notes="根據(jù)name獲取greeting info")@ApiImplicitParam(name = "name", value = "用戶名", required = true, dataType = "String", paramType = "path")@RequestMapping("/greeting")public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {return new Greeting(counter.incrementAndGet(), String.format(template, name));} }

?部署啟動服務(wù)器

訪問： http://localhost:8080/swagger-ui.html#

?

四、Swagger注解

?

swagger通過注解表明該接口會生成文檔，包括接口名、請求方法、參數(shù)、返回信息的等等。

?

• @Api：修飾整個(gè)類，描述Controller的作用
• @ApiOperation：描述一個(gè)類的一個(gè)方法，或者說一個(gè)接口
• @ApiParam：單個(gè)參數(shù)描述
• @ApiModel：用對象來接收參數(shù)
• @ApiProperty：用對象接收參數(shù)時(shí)，描述對象的一個(gè)字段
• @ApiResponse：HTTP響應(yīng)其中1個(gè)描述
• @ApiResponses：HTTP響應(yīng)整體描述
• @ApiIgnore：使用該注解忽略這個(gè)API
• @ApiError ：發(fā)生錯(cuò)誤返回的信息
• @ApiImplicitParam：一個(gè)請求參數(shù)
• @ApiImplicitParams：多個(gè)請求參數(shù)

總結(jié)

以上是生活随笔為你收集整理的Spring Boot + Swagger的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。