Swagger rest API description

 

 

1 How it works

There are more and more projects using Spring Boot to develop front-end and back-end separation, and the front-end and back-end are often in charge of different developers or teams. If the back-end develops some REST interfaces, how can these interfaces be quickly and accurately described to the front-end developers?

Swagger provides a technical implementation of automatic scanning to generate API interface documents

2 Integration steps

The first step is to add Maven dependencies as follows:

<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>

The second step is to write a configuration class;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title( "API Documentation" )
                .description("")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

The third step, write the test Controller:

@Api(description = "Test") 
@RestController
@RequestMapping("/demo")
public class DemoController {
    @RequestMapping(value = "/user", method = RequestMethod.GET)
    public Object getUsers(@ApiParam(value = "名称") @RequestParam(required = false) String name) { 
　　　 List list = new ArrayList(); 
　　　 list.add(name); 
　　　 　　　 return list; 　　} }

 Start the app and visit http://localhost:8080/swagger-ui.html

 

 

3 API annotations

Swagger also provides some @ annotations to describe the API interface in detail.

    @Api: Decorate the entire class to describe the role of the Controller.

    @ApiOperation: Describes a method of a class, or an interface.

    @ApiParam: A single parameter description.

    @ApiModel: Use an object to receive parameters.

    @ApiProperty: When an object is used to receive parameters, describe a field of the object.

    @ApiResponse: HTTP response to one of the descriptions.

    @ApiResponses: The overall description of the HTTP response.

    @ApiIgnore: Use this annotation to ignore this API.

    @ApiError: The information returned when an error occurred.

    @ApiParamImplicit: A request parameter.

　@ApiParamsImplicit: Multiple request parameters.

4 Security issues

  This public interface API document is generally only used in the development environment, and there will be certain security issues in the production environment. At this point, it can be controlled by adding the @Profile({"dev"}) annotation to the Swagger configuration class, so that Swagger will only take effect under the dev profile.