使用Swagger來產生API接口文檔技术頭條網

2020-04-06 22:48:31 JetQin90

Swagger 簡介#

現在很容易通過spring boot來實現一個rest api為服務，但是當服務直接進行接口相互調用時就需要提供相應的接口，Swagger可以很方便的通過註解的方式生成對應的API接口文檔，易於維護和spring boot有很好的集成。同時Swagger提供了swagger-ui來可以交互式的演示你的接口調用。

Swagger 配置#

依賴配置如果你使用的是Maven那麼需要添加如下依賴

<code><dependency>
    <groupid>io.springfox/<groupid>
    <artifactid>springfox-swagger2/<artifactid>
    <version>2.9.2/<version>
    <scope>compile/<scope>
/<dependency>
<dependency>
    <groupid>io.springfox/<groupid>
    <artifactid>springfox-swagger-ui/<artifactid>
    <version>2.9.2/<version>
    <scope>compile/<scope>
/<dependency>/<code>

如果你使用的是Gradle那麼需要添加如下依賴

<code>\tcompile "io.springfox:springfox-swagger2:2.9.2"
\tcompile "io.springfox:springfox-swagger-ui:2.9.2"/<code>

Configuration配置

如果你使用的是Spring boot那麼默認已經集成了web頁面訪問的功能只需增加Swagger的Configuration即可, 否則需要繼承WebMvcConfigurationSupport,然後重寫ResourceHandler保證頁面可以正常訪問

<code>    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }/<code>

<code>import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; 

import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket postsApi() {
        return new Docket(DocumentationType.SWAGGER_2) //這裡配置Swagger
                .groupName("public-api")
                .apiInfo(apiInfo())
                .select()
                .paths(postPaths())
                .build();
    }

    private Predicate<string> postPaths() {        //這裡選擇要過濾的請求
        return or(
                regex("/person.*")
        );
    }

    private ApiInfo apiInfo() {                   //這裡顯示Swagger的描述信息
        return new ApiInfoBuilder()
                .title("Upscale API")
                .description("Upscale API reference for developers")
                .termsOfServiceUrl("http://springfox.io")
                .contact(new Contact("Jet Qin","http://jetqin.github.io","[email protected]"))
                .license("Apache License Version 2.0")
                .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
                .version("2.0")
                .build();
    }
}/<string>/<code>

配置API接口#

配置完基本的Swagger之後可以開始配置Rest API接口，實現接口時建議最好使用 GetMapping,PutMapping,PostMapping,DeleteMapping等註解來代替RequestMapping RequstMapping會同時支持多種http方法，產生的接口會重複，所有通過method來限制。

配置Controller

Swagger提供了Api註解來描述Controller同時還提供了一些其他信息的配置，可參考io.swagger.annotations.Api @Api(value="person manager", tags={"Operations for person"})

配置RequestMapping 定義接口的時候最好根據需要使用不同的http method來進行限制，通過@ApiOperation可以對接口功能進行描述，定義返回結果的類型。默認的Swagger提供了對多種http返回結果的默認描述如Http 200, 401, 500等我們可以通過@ApiResponse來自定義這些返回結果的描述。

<code>@RestController
@RequestMapping("/person")
@Api(value="person manager", tags={"Operations for person"})
public class PersonController {

    @Autowired
    PersonService service;

    @DeleteMapping
    @GetMapping(value="/list",produces = "application/json")
    @ApiOperation(value = "View a list of available person", response = Person.class)
    @ApiResponses({
            @ApiResponse(code = 200, message = "Successfully retrieve person"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
    })

    public List<person> listPerson(){
        return service.listPerson();
    }
}/<person>/<code>